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Introduction 

Wek&meM^ APL *PLUS System! 



The APL* PLUS System for VAXA'MS is a version of the APL 
in:ogramming language developed especially for the VMS operating 
system. 

To jise the systm and this manual most effectively, you should be 
SiSmt^^th die APL language. If you ate not, ttgad APL Is Easy! 
fSTSC, 1987) when you get your APL ♦PLUS System running. 



JSPL Is Easy! is a tutorial that will teach you the basics of 
itti^prianti^ginAFL. For '*handsKxi''pKdce, use die demonstration 

APL programs on the disks included with your package. For details 
on the many features available in the system, refer to the APL *PLUS 
t^^i^^ence Manuals 



This manual is tutorial in nature; it contains information on the 
capabilities and features of your APL*^PLUS System. The informaUoi 
in it may be duplicated or reinforced in the APL *PLUS System 
/?^erc«ce Afan«a/. The following paragraphs outUne the contents of 

Chapter 1 shows you how to set up and access your APL*HJJS 
System. It will make you familiar with the keyboard and show you 
how to move about in the APL environment. 

Chapter 2 explains how to edit data and functions using the Session 
Manager suppUed with the system. 

Chapter 3 describes the file system. It explains the concepts behind 
APL component files and VMS native files and describes how to create 
aiid manipulate them. 

Chapter 4 explains data formatting in the APL*PLUS System and 
how to use the system fimction UFMT to format your data. 





Chapter 5 describes tffe fuU-sateeii faeilMes of the syaem, haw to 
handle the screen under program control , and how to use the 
programmable function keys. 

Chapter 6 describes the communications capabilities of the system, 
how to conununicate with personal computers, how to access the 
communicadems port, and how to transfer files and workspaces. 

Chapter 7 shows how to interact with non-APL programs and VMS 
native files, and how to issue DCL commands from APL. 

' Chapter 8 describes the printing facilities of the system and explains 
how to use them. 

Chapter 9 describes the workspaces supplied with your system and 
how to use them. 

Chapter 10 contains tips on how to use your system more efficiently 
and how to avoid the more common mors expoienced in APL. 

This manual also contains several appendixes that describe system 
characteristics and limits, the system character set, error messages, the 
use of the termcap database to support other terminals, and the policy 
on use and distribution of the Kermit transfer program. A glossary and 
index complete the manual. 

How to Read the Examples in This Manual 

All itms in APL FONT rqjresent actual system output or 
information to be entered exactly as shown. Items in lowercase italic 
font are mnemonic representations for information that you supply or 
for system ouq)ut that varies. For &maph,ia tiie foQowing 
expressitm: 

^ filename^ UPTTE tietto 

DFTIE is the name of an APL system function. You would enter it 
exactly as written. The woT6s ftlemme and tieno are mnemonic 
representations for the file name and tic number. You supply this 
information. Single quotes are used around character vector arguments; 
tliey me not ttecesmy if you use an AH. variable as the argument 
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AU items in Courier font ispeseBteitfiw output displayed by 
the operating ^rston (VMS) <x input entesed into it For sample: 

$apl 

APL*PLUS SERVICE 

i:i\:.>iiT,--.>: 

CLEAR VS 

)CMD 

$dit 

■' ■ ' Directory $DISK1 : [APL.RELB] 

APL.COM; 4 APL0TAB.;2 APLX.CMD;3 APLX.EXE;! 
ASCIITAB.;5 ATERMCAP . ; 1 AVT.HLP;! AVT.INIT;4 

Whenever possible, examples of system behavior are formatted as the 
system would format them. User entries are indented six spaces to 
match the system prompt for user input. Where user entries or system 
responses are too wide or will not fit on the page, thcsy fve wri^ped to 
•7) '% the next line with no indentadoh. Unless oth@l«i$e Rafted, # 

examples assume index origin 1 . The exceptions are g^ierally DAY 
indices, conventionally shown in origin 0. 

WhatisAPL? 

APL (A Programming Language) was originally conceived in the late 
1950s by Kenneth E. Iverson, then a professor of mathematics at 
Harvard Univosiiy. It was iititiaDy iised as a niadtemati(Sal Aotati<m 
and not as a computor programming language. In the mid-1960s, the 
notation was implemented as a programming language for use by 
IBM's cdibal research staff at the company's T J. Watson Research 
Laboratory. 

STSC, Inc., was organized in 1969 for the purpose of providing an 
improved interactive time sharing service based on the use of APL as 
' " the programming language. STSC's founders, active in the computer 
industry for many years, were convinced that APL offered significant 
productivity advantages when compared with more traditional 
languages such as COBOL, FORTRAN, BASIC, and PL/I. 
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Since STSC has hmti commit^ m wet tmmbmmmeM mi 
development effort to enhance and e;itM fte usefulness of APL. The 
result is a generalized application dev^@piR@nt system we call our 

JLUS System. Untfl IMh tte APL*H,US System was 
available only as a commercial time-sharing service. Now, however, 
the system is available to run on a variety of computers from large 
mainftmies to p^sonal computers. 

Where to Start 

Start by reading Chapter 1 of this manual. It contains the essential 
inf(Hmation you need to begin using Uie APL*PLUS System. 

If you have never programmed in APL, you should readi4PL Is Easy!. 
APL Is Easy! is an introduction to APL that was developed 
^ecifically for people begiiming to use APL. 

Almost all APL language features of the APL* PLUS System for 
V AXyVMS are identical to those on other APL ♦ PLUS Systems; 
however, some support States vary slightly because of the cottstitiims 
imposed by different computers. Also, because of the unique 
environment of your computer, some useful features have been added to 
the APL ♦PLUS System for VAXA^S that do not tspp&st in other 
APL* PLUS Systems. These unique features are noted as system 
dependent or experimental in the APL *PLUS System Reference Manual. 

How to Get Help with Your System 

STSC wants you to get the most benefit from the APL * PLUS 
System. These guidelines will help you to obtain the best support 
firom STSC, 

Register Your System 

STSC provides support and assistance only to registered software 
licensees. Use the Registration card to register your System. 
Registered system owners will receive information about updates to 
the system including news of new versions, bug fixes, new features, 
and other information of interest to APL* PLUS System users. 
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The Help Line 



STSC's Help Line has been established to provide timely assistance to 
registered users of the AFL«H<US System. If you need assistance 
with the product want to lepoit a problem, write to tte following 
address: 

APL * PLUS VAX/VMS Ktig Line 
STSC, Inc. 

2115 EietJeffnson Street 
Rockville. Maryland 208S2 

You also can caU the One tmmbabie^, Skf^ dMpbotw k 
answered for a limited numbers of hours, youifiay hear a ieiC{»ding that 
tells you when you can reach us. Call: 

(800)638-6660 

«' in N^land w outside the U.S. call: 

(301) 984-5140 
Please be ready to provide the following information: 

• your name 

• your organization 

• the nsimeof the registered owner of the sysesiii 

• the serial number of your system (on the diskette) 

• the version of the software you are using (enter □ S YSVER). 

Report Appannt Errors Ote Software to STSC 

•#!K6t^ger to lemn of suqiee^ piobteins with the system and you are 

invited to report apparent bugs to STSC. We want to resolve problems in 
future versions of the system so that all users benefit. We may receive 
multiple reports of a single proyem, so if the di^ulty is not interfering 
with your use of the system to an important degree, please write. If the 
{Hoblem is causing you considerable difficulty, you should call the Help 
Une. 
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You can help us find and fix a bug by providing specific information about 
the cause of the problem and the result. If you can narrow down the 
IHd)Im to a few lines of input in a dear wsskspac^, it will make it much 
easier for us to find and fa the ptoblon quickly. 

STSC Offers APL Instruction and Consulting 

STSC offers all levels of APL instruction, application design consulting, 
and full application impl»nentation at your facility or at STSC 
headquarters. Contact STSC for more information about class schedules 
and tuition fees, and consulting rates. 

Can I use the APL *PLUS System on Other Computers or 
Other Operating Systems Similar to the VMS Operating System? 

The APL* PLUS System is designed for the VMS operating systems or 
close derivatives. A different STSC product is required to nm the 
APL^FLUS Syston on a non-VAX computa or to nm on a VAX under 
UNIXorULTRIX. 



Aclaiowle^meiUs 

Many people contributed to the design and {soduction of the APL*PLXJS 
System for V AXA'MS and the documentation. The editms are grateftd id 

them all, especially: 



Larry Goodwin 
William Lewis 
Edward Myers 
Mark Osborne 
Marvin Rouch 



Richard Renich 
Stuart Ritter 
Laurie Russell 
William Rutiser 
Muy Wise 



torn' Comments Are Welcome 

We appreciate suggestions of new features that might increase your 
peduetivity. We pardciilatly lite to know what features you would like to 
seeenhaneed and what new features you would find useful. We design 
future releases based on suggestions we receive. Send your suggestions to: 
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APL*PLtJS VAX/VMS Produet Manager 

STSC, Inc. 

21 15 East Jefferson Street 
Rockville, Maiyland 208S2 

Comments about this manual are also welcome. Please send your 
comments to: 

Technical Documentation Manager 
STSC, Inc. 

21 15 East Jefferson Street 
Rockville, Maryland 20852 
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Chapter One 
Getting Started 



The Installation Guide describes the procedure for installing the 
APL * PLUS System on your computer. The material in this chapter 
assumes that the instructions have been followed and Utat APL has 
been installed in the directory [APL.RELnJ.ii^^re Aistherdease 
number of ^our APL*PLUS System. 

1-1 Hardware and Software Requirements 
Required Hardware Configaration: 

• 2 megabytes nMin^Mcy 

• 200QbIbcks&eeaatltesistallationdisk 

Opera^lnig System Requirements: 

• VMS or Micro VMS Version 4.4 or later 
Recommended Hardware Configuration: 

• Additional memory is required ffv eSSdoit use of large wt^cspac^ 
or for multiple users. 



Teinninals Supported: 



•fi' .;i:i'.;»>r ; 



.» -,1: ..-vv ' - 



Digital VTIOO 

Digital VT200 swies 
HDS AVT 
HDS Concept 108 
HDS 200 series 

HP 2641 

IBM PC running APL ♦PLUS PC System 
Macintosh running APL* PLUS Mac System 
Generic APL video or hardcopy terminals 
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Note: Terminals are supported through the use of the termcap 
database (see Appendix D). You can add new tenninals to the database. 



1-2 Beginning and Ending an APL Session 

Once installed, the APL* PLUS System can be invoked by the 
following DCL command (the $ used here is the prompt displayed by 
VMS): 



Terminal name: 

Enter the abbreviation that identifies your terminal. If your terminal 
does not appear on this list, select g or h. APL will use a generic 
tMin bial definidon which ^sanies a Iin&«dmed tennunl thai behaves 
like a hardcopy terminal. Full-screen editing is not available for the 
generic terminal. 

APL is a large program and usually takes several seconds to load from 
disk. When the system is loaded, a welcoming banner displays, and 
the iiiteiactive session begins. The message CLEAR VS appears, 
and the cursor indents six spaces on the next line. Depending upon the 
kind of terminal you are using, the screen may be cleared and the 
tenninal switched iato the APL character set 



$ apl 



A list of suip)rted terminals should be displayed: 



pc 

cl08 

avt 

c200 

hp 

vtlOO 
vt200 

g 

h 



IBM PC running APL*PLUS PC 

HDS Concept 108 

HDS AVT 

HDS 200 

HP 2641 

DEC VTIOO 

DEC VT220 and VT240 
generic APL video terminal 
generic APIi hardcopy terminal 
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r: :t!ii" ..lyliiH.-. 



Ail^ sbouM iboi di^lay a screen similar to this: 



APL*PLUS SYSTEM FOR VMS VERSION 1.0 SERIAL NUMBER 1234 

coPYRimT i9ts. im sfsc. mc. all nmm MSMmo. 



CLEAR VS 



SCmW 1 APL SESSION Ins APL 



The me named apl is a DCL command procedure that performs 
several actions to set up the APL session. It will be installed as 
[APL . RELn] APL (where n is the release number) on one of the 
system disks. If the System Administrator at your site has followed 
the installaticHi p^edure recommended by STSC, the name Af Ii wIH be 
defined as a synonym for this command in the file SYSLOGIN . COM. 
The instaUation procedure also recommends that the synonym 
APL DX;^ be defined for die disk on which AH. is instalied. 

Once you become more familiar with the APL * PLUS System, you 

^rofeybly want to cusKmize [kbl . BELa] apl io your 
prrfoencss (see Section 1-3). 

Now test that APL is configured contectly for your terminal by typing 
in a simple expressi(xi such as: 

2 + 3 
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If APL prints the answer properly, the configuration is correct (If the 
result displayed is 0.666667 instead of 5, you typed in the symbol for 
APL division ^ , which is on the key where + appears on a non- APL 
terminal.) 

Once APL is started, it remains active until you type the command: 
)OFF 

$ 

If this command does not work, you probably are not using the keys 
that APL expects. If your terminal is not an APL terminal or a 
Personal Computo' widt STSC's An. characters installed, try "off 
(double-qiiolB followed by unshifted ofO- These are the keys on a 
regular losyboatd that correspond to ) OFF on an APL keyboard. 

Exiting from APL terminates the APL process for VMS. Open files 
are closed; the contents of the active workspace are discarded, and the 
tmmsl b^vior is restored to what it was what APL was first 
invoiGed. 



i-3 The APL Command Procedure 

The command procedures pnmded with the AEL*FLtlS System for 
VAX/VMS in directory [APL.RELn] are for configaangttiiSEyslein 
to specific APL terminals. These can be used instead erf ttie geno^ 
apl procednre, which iRompts for the Idnd of terminal you are using. 

Files of the form nnnAPL . COM, where nnn is a terminal type, are 
eOiimiaild procedures for running the APL*PLUS System. Each 
command file turns off the DCL Ctrl-y and Ctrl-t functions and starts 
APL with a specific initiahzation file. 

The distributed command files and their associated initialization files 
are: 
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Terminal Type: 



Command File 



Init File 



general or unknown: 
HPS AVT terminal: 

HDS 200 series: 
HP 2641 terminal: 

I running the 

APL*PLUS PC System 
in terminal mode: 
DEC VTIOO terminal: 
DEC VT200 series: 
generic APL video: 

,»fm^^«AH. hardcopy: 



APL.COM 
AVT APL . COM 
C108APL.COM 
HDSAPL.COM 
HP APL . COM 



PCAPL.COM 
VT100APL,C5C»1 
VT200APL.COM 
GENERICAPL . COM 
HARDCOPYAPL . COM 



GENERIC. INIT 
AVT. INIT 
C108 . INIT 

HDS200 . INIT 
HP2641 . INIT 



PC. INIT 
VTIOO. INIT 
VT200.INIT 
GENERIC . INIT 
HARDCOPY. INIT 



If the Syst^ Administrator at your site has followed the installation 

procedure recommended by STSC, the following synonyms will be 
defined and may be used to execute the corresponding . com command 



APL 
AVTAPL 

C108APL 
HDSAPL 



PCAPL 
HPAPL 

VTIOOAPL 
VT200APL 



I • ■ I - U^S& System Administrator has not already established global 
' " ^ I l^fiumyms for these commands for all users, users can edit their own 
'iii. LOGIN. COM file to add a line such as: 



$ hdsapl :== "@apl_disk : [apl . rein] hdsapl" 
Ilus will allow the user to invoke APL on an HDS 200 by typing: 
hdsapl 



1-4 Terminals for APL 



The APL *PLUS Systoii for VAXA^S uses a file of the same 
structure as the UNIX termcap database to describe the full-screen 
bdiavior of various terminals. A file named atermcap is provided 
on the distributicm tape. 
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The atermcap database allows effective use of a wide variety of 
terminals with the system. Appendix D explains how to su^)Oit other 
tenninals not included in atermcap. 

This section will also discuss the special support provided for the 
VT220 and VT240 terminals and the IBM PC when using the 
APL*PLUS PC System in terminal mode. 

Using the VT220 and VT240 Terminals 

The DCL procedure VT 2 0 0 APL . COM on the distribution tape takes 
advantage of the capability of fonts to be downloaded on the VT220 
and tominals and msdces them effective as APL tenninals. The 
CtMlfigiUation file VT200 . INIT loads useful values into the 
tominal's function keys and configures APL to recognize its editing 
keys. The APL keyboard fOT the VT220 is as follows: 

VT 220 Keyboard 



$ 

0 T 







< 


< 




> 


> 












1 I 


2 V 


3 t 


4 i 


5 <t> 


6 (S 


7 e 


8 9 


9 v 


0 * 


+ ! 


X i 





? 


u 


£ 






t 


4. 


i 


o 


★ 


{ 


} 




Cmd 


Q q 


W w 


E e 


1 . 


T t 


Y y 


U u 


I i 


0 o 


P P 


*■ a 


■* * 


Enter 



Ctrl 



Lock 



a 


r 


L 




7 


A 


O 




0 


( 


) 


A a 


S s 


D d 


F f 


G g 


H h 


J j 


K k 


L 1 


[ i 


] * 



Shift 





c 


D 


n 


u 






1 


» 




\ 


s 


Z z 


X X 


C c 


V V 


B b 


N n 


M m 




! >t 


/ / 



Shift 



Shifted-* 
Unshif ted-» 



«-Alt 
(when preceded 
by Alt-key) 





Insert 
On/Off 


Untype 


Alt 


Page 
up 


Page 
down 




Cursor 
Up 




Cursor 
Left 


Cursor 
Down 


Cursor 
Right 
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. function keys on a VT 220 are defined inVT20Q,iNiTas follows: 



Kev 


Unshifted 


Shifted 








F7 


OvPfctTiIrp 


Delete line (CmA D Vt\ 




r)plptf» rh^r 


5?nlit line CCmd 1 


F9 


QearEOL 


Join lines fCmd h 


FlO 


O-U-T 


In<iert raved tines below fOnd 


Fll 


Undo 


Insert saved lines above fCnid *^ 




XWll vOll 


Save line fCmd Y 


F13 


Scioll down 


Strinff search f Cmd t\ 

Vi#W»&aft^b l^vWavBA ft^rivA*%» / / 


F14 


Scroll up 


Repeat search (Cmd/RBTURN) 


F17 


CmdZ (editor end) 




F18 


Cmd S (lo ses^) 




F19 


Cmd E (editor begin) 




F20 


Cmd Q (editor quit) 





See Section S-1 for more informaticHi on function keys. 



VOng Ote A^l,*PLUS PC System as a Terminal 

A PC running the APL*PLUS PC System in terminal mode can be a 
very effective terminal for the APL*PLUS System for VAXA'^MS. 
, The following steps are necessary in order to make the best use of the 
..PC as a full-screen terminal. 

On the PC (version 5.0 or later required): 

• Execute the function TERMINIT, listed below. 

• Turn off the status line, using ScroU Lock, to prevent conflict with 
the stam lioBlnoaioed by APL*FLUS finr VAX/VMS. 

* . Svd\(A into temunal mode (Alt-F8). 

Or tiie VAX, run the DCL i^i^rani PCAPL . COM, which runs APL 

with the terminal type of pc. Alternatively, run APL . COM and 
specify pc in response to the terminal : prompt 

After you complete the previous steps, the most common keystrokes 
will have the same effect on the APL* PLUS System for WAX/WMS 
as diey do on die PC. The keystrokes affected are: 
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Backspace 


Acts as the Untype Key 


Ctrl-C 


Signals an interrupt to halt APL execudon 


Home 


Moves ctirsor to left end of the line 


Ctrl-Home 


Moves cursor to the top left of the screen 


End 


Moves cursor to the right end of the line 


Ctrl-End 


Moves cursor to the bottom right of saeea 


t 


Moves cursor up one line 


Gtrl-t 


Moves cursor up four lines 




Moves cursor down one line 


Ctrl I 


Moves cursor down four lines 




Moves cursor left 


Ctrl-- 


Moves cursor left eight spaces 




Moves cursor right 


Ctrl-- 


Moves cursor right eigjit spaces 


PgUp 


Scrolls up one line 


Ctrl-PgUp 


S^lsttp(mepage 


PgDn 


Scrolls down 


Ctrl-PgDn 


Scrolls down one page 


Alt - 


Qearstoendof line 


Del 


Deletes character and close up 


Ins 


Forms overstrike with next keystroke 



The PC's Alt keys (such as Alt-4 for i), will produce the expected 
composite character only if the APL* PLUS System for VAXA'MS 
is in overstrike mode. The PC's terminal mode transmits 
'A',DrC5S , ' I ' when Alt-4 is pressed, and the oversu-ike will not be 
formed if the VAX is in insert or replace mode. You can achieve the 
effect of the Alt-keys even if the system is not in overstrike mode, by 
first pressing ESC and then the key that you would ordinarily use with 
Alt on the PC. 

Execute the following APL function on the PC to customize terminal 
mode appropriately: 

V TERMINIT iS:OSEG;TAB; 010 

111 n Initializes APL*PLUS PC foruse as a VMS tnroind 

121 DSEG^' ' 

[3] S*-\nPOKE 115 PI FuUdi^lex 

[4] S-127 0 OPOKE 171 172 n Suitable untype sequaice 

ES] 

[g] fl Oater pc^ for special editing 

E7] ni(M> 0 TAB-^aAVl91 
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[8] S^6t 138. aAViTAB,'h' fl Home — TABH 

1.%}. .- ^.^V,§.f^UV ' ^AVvTAB ,'k< ,TAB. ' h < fiCtrHtorae^TAB KTAB H 
CIO] S-^S.Bf 136. nAViTAB.'iy n PgUp — TAB lY 
[11] S-^S, &m2. DAViTAE, ' Ic' h Ctrl-PgUp — TAB 1 C 
[12] S-^S. Sri32. UAViTAB, • 1' r\ END — TAB L 
[13] S^S ,6tllA .OAViTAB ,< J ' .TAB,' 1 ' nCtil-END— TAB JTAB L 
tl43 S-^S,6n65.DAVlTAB.<lu' H PgDn —TAB 1 U 
'-^■^fii^Sr'eft'iB ,UAViTAB , nv' n etri-PgDn — ► TAB 1 V 
[16] S-S, 6tl77 16 fi INS — Ctrl-P (overstrike) 

[17] S-S, 6 1 176 4 H DEL— Ctrl-D (delete char) 
[18] nSEG^" DSEG^25SiOPEEK 130 129 
[19] 0 0 pS QPOKE 1102+ipS 
V 

See "Using Terminal Mode" in the APL*PLUS PC User's Guide 
(Release S.O or later) for details on how Ae tenninal mode behavior 
caii.t!^p)}Stoinized. 



1-5 Using the Keyboard 

The APL*PLUS System for VAXA'MS has been designed to provide 
a user-Mendly, full-screen interface, no matter which of dozens of 
different terminals yenahiiff be D^g. Getliagtheniostoatofso 
many different terminals means that APL must be very flexible in how 
it treats the terminal. This means, however, that you have to ensure 
Aat APL is set iq> prop^y to woik witt yov tenninal. 

Terminal features and behavior can vary considerably. For example, if 
your termind a emsor-up key lia3)6led wi A an upward-pointnig 

arrow, you would probably like to be able to press this key in APL to 
move the cursor up one line. If your terminal is an IBM PC running 
the APL* PLUS PC System, pressing the cursor-up key transmits a 
Ctrl-K character to VMS. On the other hand, if your terminal is a 
DEC VTIOO , the cursor-up key transmits three characters: Escape, L, 
and A. SometaminalshavenocursOTkeyatall. 

In order to deal with these differences, the APL * PLUS System uses 
the concept of logical keysuokes. A logical keystroke is defined in 
terms of the effect that a key on die terminal is expected to produce. 
For example, "cursor-up" is a logical keystroke — it is a command 




at the tenninal that instracts APL to move the cursor up 
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one line. The exact key tiiH ^ l& achieve ttiis command will 
vary bam one terminal to anMl^, but the effect is the same. 



Of course, this can only work if APL knows what sequence of 

characters is intended to represent ciirsor-up, which is why it is so 
important that the terminal interface be set up properly. The 
following tables show APL logieal heystKlIm and thdr effects on 
some popular tenninals. 



Input and Editing Keys 
Keystroke 
lAiiype 

Ddete 

Oear-EOL 

Undo 



Alt-key 



Overstrike 



Enter 



CtirsorKeys 



difSor-up 

Cursor-down 



LogietfKQrstrokes 



Effect 

E)(^eie the most teoendy ^ped ^timcm (the 
character to the left of the cursor) and close vcp. 
Also called desu^ctive backspace. 

Delete the chaiacta: at die cursor and close up die 

space. 

Erase all characters from die curscnr to die end of 
the line. 

Undo all changes Uiat have been made to the line 
and repDmpt 

Intnpret the subsequent keystroke as an "Alt" key, or 
a logical Program Function key (see Section 5-1). 

Ovo'suike the character to die left of die cursor widi 
die next characto' typed. 

Enter die current line as input to APL. 



Move die cursw up one line. 
Move the cursor down one line. 
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Cursor-left 
Cursor-right 

Window Control Keys 
Scroll-up 

Page-down 
Input Mode Control: 

APL-keyboard 

Text-keyboard 

Insert-mode 

Other Comituinds: 

Command 

. Interrupt 



Move the cursor left one i^ace without erasing 
what is thrae (non-desdnctive backspace). 

Move the cursor right one space without erasing 
what is there (non-destructive space). 



Scroll the active window up one line to reveal a 
Une saved in off-screen memory. 

Scroll the active window down (me line. 

Move the active window iq» ompage (one 
saeen-fidloftext). 

Nfove the active window down one page. 



Switch APL to interpret keystrokes as coming 
from a terminal with an APL keyboard. 

Switch APL to treat the keyboard as a standard 
non-APL keyboard. 

Switch between insert mode, replace mode, and 
ovastrike mode. The current mode is shown on 
liie status line. 



Interpret the next keystrokes as session 
managers-screen edteoxnmand. See 
Chq)ter 2 for details on editor amunands. 

Interrupt ait iSMCuting APL program or die display 

of output (functions like the BREAK key in some 
other AHL systems). Always a '^C under VMS. 
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0-U-T 



Interrupt Q input Qite the 0-U-T escape sequence 
used on older APL sj^tems). 



Sefiedi Oear die screen and le-display its contents. 



The fofloidng tafele ^xms the physical keys used to produce logical 
keystrokes what ifae proper configuration file has been used on these 
terminals: 

• VT220: VT200INIT 

• HDS Concept 108: C108.INIT 

• SMted ASCH tenninid with no . Xtf iT file used 

• AFL*FLUS PC tenninals: pc.init 

Logical Keystrokes oa Selected Terminals 

Ascn 

terwlmd 







EDS 


with no 


APl.*PLUSPC 


Keystroke 


Tenninals 


cm 


config flle 


Terminals 


Untype 


Remove 


Backspace 


Ctrl-R 


Untype 


Delete 


F8 


Ctrl-D 


Ctrl-D 


Del 


Qear-EQL 


F9 


Csd-E 


Clrl-E 


Alt-nght-airsor 


Undo 


Fll 


CMS 


Clrl-B 


Ctrl-i 


Alt-key 


Select 


Ctd-A 


Escape 


Escape 


Overs trike 


F5 


Ctfl-P 


Ctrl-P 


Ins 


Enter 


Enter 


Romn 


Return 


Return 


Cursor-iq> 


Cursor-i^ 


Cutsor-up 


Clrl-K 


Cursor-19 


Cursor-down 


Cursor-down 


Cursor-down 


Ctrl-J 


Cursor-down 


Cursor-left 


Ciirsor-left 


Cursor-left 


Ctrl-H 


Cursor-left 


Cursor-right 


Cursor-right 


Cursor-right 


Ctrl-L 


Cursor-right 


Scroll-up 


F14 


Scroll-up 


Cirl-Y 


Ctrl-Y or Pagc-up 


Scroll-down 


F13 


Scroll-down 


Cirl-U 


Ctrl-U or Page-down 


Page-up 


IVevious-Setecn 


Page-up 


Ctrl-C 


Ctri^orCtrl-Page-up 


Page-down 


Next-Screen 


Page-down 


Ctrl-V 


Ctrl-V or Ctrl-Pagc-down 


APL-keyboard 


Ctrl-Y 


Ctrl-N 


Ctrl-N 


Ctrl-N 


Text-keyboard 


Ctrl-O 


Ctrl-O 


Ctrl-O 


Ctrl-O 


Insert-mode 


Insert-Here 


Ctrl-T 


Ctrl-T 


Ctrl-T 


Command 


TAB 


TAB 


TAB 


TAB 


au-T 


FIO 


Ctrl-Z 


Ctrl-Z 


Cirl-Z 


Refresh 


F12 


Ctrl-F 


Cirl-F 


Ctrl-F 
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Interrupting APL 



The interrupt character for APL is Ctrl-C. You can use this character to: 

• halt execution whenever APL is running 

• interrupt the display of a large volume of output 

• break out (tf die delay from DDL and □FffOtD. 

During the time that APL is expecting input, Ctrl-C is the default 
page-up character, and it does not intmupt anyibing. Oa Aill-screen 
teaniUQals. it is easy to teU whedia AFL can be interriqHed: 

• If the status line is hiddra, thai AH. is ninni^iu^ Ctrl-C acts an 

• If die status line ^v&ibJei then AFL is awaiting input, and Ctd-C 
;,iftr-v.^ not act as an intemipL 

You can also use Ctrl- Y to end dK AFL pmeess aad KitMi yoa 
. . immediately to VMS. This event cannot be trapped by any error 
handling routines, and your active workspace and all record of your 
APL session will be lost. You can sc^qiress diis effect of Ctrl-Y by 
using the DCL command 

set nocontrol*y 

in die DCL procedure before invoking APL. This prevents Ctrl-Y 
from interrupting APL, although the message INTERRUPT is still 
displayed on the terminal. Ail of the APL command procedures 
provided by STSC already contain this settteg. 

Editing Input 

APL input is displayed on the terminal as you type it, but no action is 
1 ■ taken until you press Return. You can make any son of correction 

before altering the Une as input, and the terminal displays the 
corrections. The Untype key is particularly useful for immediately 
erasing a mistyped character and typing the correct one in its place. 

If you want to discard the line completely and start fresh, the Undo key 
will erase everything you have typed on the line so you can begin 
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again. Part of the line can be erased by backspacing and using tiie 
Qear-EOL key. 

Forming Overstrikes 

The APL composite characteis. also caUed overstrikes, can be formed 
in three distinct ways: 

• The ovcrstrike key will combine the character to the left of the 
cuisw (the one just typed) with the next keystroke typed. To 
produce i, type the duee keystrokes a, Ovostrike, and I . 

■ The Alt-key mechanism is often handier for typing composite 
characters. For example, Ak-4 will prodnGe 4 (assumiagfhat you 
have not cqxogrammed the Alt-key con^ts). 

• In overstrike mode, a chaacter already on die screen can be 

overstruck with another by placing the cursor on the character and 
typing the second character. This does not work in "insert" or 
In^iboe" mode. 

Input Errors 

If you type a keystroke that has no meaning to APL, or if you attempt 
to form an overstrike character from two keystrokes that do not 
combine to fbrm a composite characto', die tBcniyMi wQl iMlciie an 
error either by flashing the screen or sounding Ihe bell, dqwnding upon 
the kind of terminal you are using. 

Insert, Overstrike, and Re^aee Mode 

For CRT terminals, the system is in "insert" mode by default. Text 
typed in the middle of a line is inserted at the cursor, pushing any 
diaracters beyond die cursw to the right The insert-mode Isey will 
switch the keyboard between insert, overstrike, and replace mode. 
CRT terminals may also have a status line that indicates whether the 
terminal is in insert, replace, or overstrike mode. 

In "rq)lace" mode, characters typed at the terminal replace tlie character 
already present. Replace mode is convenient for reading user input 
under application conuol. In replace mode, typtaig a space will 
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substitute a blank space tm tt» ctmcmxsr skesidy present «i smm. 
Tte cumnviii^t key ^pac^ past a character. 

In "overstrike" mode, an APL composite character can be formed by 
typing one symbol, backspacing, and typing the second symbol. 
Overstrike mode can be usefiil when you want to form multiple 
overstrikes at once; fcHr example, you can enter • (|) e ^ by typing 
* I ^ \ .. fiaUowed four backspK^ and four o chai^^. 




If you are using a terminal that can switch between displaying APL, 
characters and regular ASCII characters, then you can use the 
r-.--ji?h sv? APL-keyboard and text-keyboard keys to switch keyboards. The^ 
v keys do not actually modify what the keys on the terminal transmit, 
but they do control how APL interprets characters received from the 

In the APL keyboard state, typing the unshifted A key yields an upper 
case A, and typing it while holding down the shift key yields alpha 
(a). In the text keyboard state, the unshifted key produces lowercase 
V and the shifted key the upper case A. 

Some characters can be produced from either keyboard. For example, 
" •tmmbtisk (*) is the Sane charsKter whether prodtKed witfi a shtft^Pto 

the APL keyboard or shift-8 on the text keyboard, and lowercase "a" on 
the text keyboard is exactly the same as A overstruck with an 

APL Alphabet 

The APL *PLUS System's chaiactrar set contains the upper^se Mers 

ABCDE . . . XyZ and the lowercase letters a jbcde . . .xyz. The 
lowercase letters correspond to the underscored alphabet used in 
traditional APL systems. On terminals that are incapable of 
displaying both APL and ASCII characters at the same time, including 
most hard-copy terminals, the lowercase alphabet is displayed in its 
tradition^ fcxro of M£M- . . XYZ . 
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1-6 The Session Manager 



The Session Manager manages the input and output between the user 
and the APL interpreter. The Session Manager and the full-screen 
editoi' are actually the same program, except that the fidl-soreoi editor 
is used to edit APL functions and variables. The same keystrokes and 
commands are used by both, providing a consistent environment for 
^ASLmet. Mae details on the full-screen editw can be found in 
C3i9pler2. 

All APL taput you type and an output produced by AH. is recOTded in 
a logical scteexi image stored in the computer. The logical image 
typically contahis more lines than can appear on the screai at once. 
One dT the most important functicnis of the Session Nbnago^ is to 
keep the image that appears on the terminal consisient witt the image 
stored in memory. 

With the Session Manager, you can use the entire CRT screen for 
APL inpuL You can move the cursor to any position on the screen, 
insm or chaRiCteis, or sendl up and ^ 
bas moved out (tf die visiUe window. 

Moving the Cursor 

The cursor movement keystrokes (cursor-up, cursor-left, and so on) are 
used to move the cursor on the terminid. The Session Manager keeps 
track of the codes transmitted when you press the cursor keys. It also 
transmits conuol codes to the terminal to keep the visible cursor 
position consistent with the cursor position known to APL. Many 
fiill-screen editor commands can be used to move greater distances on 
the screen or even to locate a specific text string in the session image. 

Re-Using Previous Lines 

When the APL* PLUS System is expecting input and you press 
Return, the line on which the cursor rests is passed to the APL 
interpreter as input Thus, you can re-enter any line of input or output 
that is visible on the screen by moving the cursor up to that line and 
pressing Return. You can modify the cuneqt form of a line using 
e^ttog keystrokes and thai eata the modified line. 
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If APL is in immediate execution input mode, and you move the 
cursor up to use an earlier line to satisfy the input, the line is copied 
to the bottom of the screen when you hit Return. If you make 
changes to the line bef^ pressing Remm, the new form is copied to 
the bottom of the screen and the old line is restored to its original 
form, keeping an accurate record of the APL session. When not in 
imniediate exeeute fltode (dteA is, in ^ ddi effiiev (V S 
does iKH copy re-used lines to the bottom of die screen. 

SenlUng 

To understand the scrolling capabilities of the Session Manager, think 
^ the'titnibua mtea as a window ttwt di^biiys oeiy part oi diet haptit 
apjd output that has been generated io tbO course of the APL sessi^ 
tfte ilession Manager maintains in ntemory a record of recent ouQnit, 
storing more lines than can appear on the screen at once. Soolling is 
the process of moving the wbdow iq> and down duough die stored 
' screen images. 

^Scrolling occurs automatically when all lines on the screen have been 
used and a new line of output is produced. All Unes on the screen move 
(ip one position, and the topmost line disappears. If you move the 
cursor to the top Une of the screen using cursor-iq> and press cursor-up 
again, you will "push" the window up cnie line to reveal die tfiie dmt 
had disappeared. Similarly, pressing cursor-down when the cursor is at 
the bottom of the screen will push the window down one line. 

The scroll-up and scroll-down keystrokes are used to scroll the window 
up and down a line at a time without changing the cursor position. 
Page-up and page-down move 19 and down a soeai^ or "page" at a 
time. Other editor commands can be used to move the window in 
additional useful ways. Chapter 2 discusses the full-screen editor and 
its conunands in detail. 

If you are at the top of the scrolling memory and try to move up 
farther, the terminal will Iteep oc flash the screen. The same effect is 
produced by attempting to move down past the last Une. Only a 
limited number of screens of output are saved for scrolling; you can 
specify how many with the session parameter screens= (see Section 
1-7). By default, the system saves four scteens-fuU of output. When 
Ae scrolling memory is full, new output is inserted at the bottom of 
die scrolling monory, and the top lines are discarded. 
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On-line Session Afanojger Documentation 

TTie system command ) HELP displays a summary of the keystrokes 
sbA commands used by the Session Manage and M-so'^n editor. 
The iiionBati(» displayed is extracted from a VMS file wlKise asuoe is 
iq)ei^^tf the APL session parameter he lp= (see Section 1-7). If 
no hdp file is specified, the default file is used: 

[APL . RELn] HELP . HLP. 

1-7 APL SesidonPanmeters 

Session parameters control various options to AFL scions. They 
also convey information to APL about the terminal are using. 
Specify session parameters by typing them on the sani& Une as the 
AFL imm6m, or by inching than in yoat configuElta fite; 
Following aie seme examples of sesaon parametos: 

$ apl 400000 

Specifies the initial size of the active workspace to be 400,000 bytes. 

$ apl editineni=40Q00 screens'^lO 

Specifies 40,000 bytes for sesii^ mm»$st and full-screen editor 
memory, with 10 screens of ouq)ut saved in the scrolling memory. 

$ apl initfile= [apl. tell ipc.init 

Specifies that the file apl_disk : [apl . relI] PC . init will be 
MSsA as a eonfigue^m ffle; ttis particular file (pc . isrif) is used 
when the terminal is a PC running the APL*HLUS PC System in 
terminal mode. 

Many other session parameters also exist. Since there are so many 
different session parameters, we recommend that you use a 
configuration file to contain them, Conflgimticw files lOe fll^ that 
contain APL session parameters; their structure is described in Section 
1-8. The default APL command file, which is typically installed as 
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file command apl, selects a configuration file for you based on the 
type of terminal you specify. 

The parameters that you can supply v/bm sttwting APL are listed in 
the following table: 



Parameter 


Deseriptfon 


nnn 


Workspace size in bytes (de£ault=16384) 


editmem= 


SessionAeditor inanory (de&ul^=6Si53^ 


help= 


Name of help file 


initf ile= 


Name of configuration file 


initialws" 


filiiid wixfcspace n^ne 


library= 


D(£ne library/directory mapping 


outputtrt= 


Name of output translate table file 


prompt= 


String used as input prompt 


screens= 


Number of screens saved in session 


status= 


Initial terminal state (default=0) 


termcap= 


Name of termcap database 


terniciinit= 


String sent to terminal cm exit from APL 


terminal= 


Name of terminal you are using 


tenninit= 


String sent to terminal at entry to APL 


ternitype=b 


Bit-paired terminal 



Each of thesesaonpaiametessisdesaibedinmofedeiailintflis 

section. 



Workspace Size 



The initial size of the APL workspace is specified by a session 
parameter that consists of a number with no qualifier. For example: 



$ apl 200000 



specifies a 200,0(X)-byte workspace. If the size parameter is missing 
or incorrectly formed, or if not enough memory is available for the 
requested size, the default workspace size is used. The default size is 
the smaUest possible workspace, 16384 bytes. 

Hie maximum woik^ace size is determined by the process size limit 
and the amount of process memory available to VMS at the time APL 
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is invc^ed. If ydur teqaest is f&t a liitpr rna^^^ 1W can 
provide, APL displays the message INSUFFiCIMHf SPACE 
FOR VS and uses the default size. 

Once APL is running, you can inciease or decr^ise the workspace size 
using ) CLEAR: 

)CLEAR 150000 
CLEAR VS 

)CLEAR 900000 
INSUFFICIENT SPACE FOR VS 
CLEAR VS 

See Section 10-3 fpr inftnrmation on how to inciease the woiic^pace 
size limit. 

Full-Screen Editor Memory 
editineia= 

The amount of memory allocated for the APL session manager and full 
screen editor can be specified with the editmem= bytes. For example 

$ apl editmein=50000 

allocates 50,000 bytes of memory for the editor. This memory stores 
the logical image of the APL session as well as the images of objects 
being edited Id die full-screen editor. Theme^e NOT ENOUGH 
MEMORY AVAILABLE from the full-screoj editor indicates Uiat 
the current allocation has all been used. 

The default allocation is 65,536 bytes, and the editmem= bytes can 
specify any value from 16,3S4 to as large as VMS will allow. 

HttpFaettity 
help= 

The session parameter help= specifies the name of the file that is 
read and displayed by the APL system command )HELP. The help 
facility allows you to display the contents of the file, one screen at a 
time, or to review a screen that has already been displayed. If the 
help= option is not used, the default help file is used: 
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[M>L . REXh^lilEIiP i HLF 



1 ■ •■r'-; ;i ; , ) f/fL P proviSes Only a Very simple help facility and is not 

; recommended for incorporation into applications. The primary use of 

the facility is to help you remember the session manager and 
fiitl-sereai editor eornniands. FtvddsieasOR/youim^iinmttowijtea 
specific help file for individual terminals and to include the help= 
parameter in the configuration file for that terminal. 

1. ... , ., The distributed file HE LP. H LP is a good example of the structure and 

content of a help file. Note that the VMS line-feed character 
(□Z';C£.f> is intgpil^ as the line delimits in HELP . hlp. 

Configuration Fik 

The initial file is a configuration file that contains session parameters. 
.'. *Obls' k>:«rT(.rf-i js*. ^--P'r-hj 'K-: vf*. : See Section 1-8 for details cm using liiltflle- and creating a 

■ , : configuration file. 

Initial Workspace 
•■ i ,| ,initialws= 

The initial workspace parameter initialws= specifies the name of a 
woiks^ce that APL will load automatically at the start of the session. 
^ ■ .'^ if'tfleinttialwod[qpacec<mtamsa]^^ 

application can be started automatically. The wodcspace name is 
specified as the name of the VMS file that contains the saved 
wcnkspace but without die .ws extension. For example: 

- $ apl initialws=autostart 

If no explicit path is provided, the workspace is assumed to be in the 
current default direcuxy. 
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Library Number 
librax3p 

The session parameter library= equates a library number with a 
VMS^ectoiy. This feature can be used to faKxt^eqnipKibiUty 
with oth»' APL systems that use library numbera. Vot example: 

library=ll [apl.rell] 

defines library 1 1 as corresponding to the directory [ apl . reli ] . 
Moie infonnation on munbored libraries is in Ouster 3. 

Output Transldton 
outputtrtB 

The session parameter outputtrt= specifies an optional output 
translation table that is used instead of the translate table built-in to 
the system. This table controls the character sequence transmitted to 
die tominal for each of the 2S6 possible APL characta values. All 
normal APL output to the termuial is affected, including i^ut diat is 
displayed while you type. 

The outputtrt= parameter is primarily used to make APL work 
with specialized terminals that do not conform to die APL/ASCU 
typewiiter-paired standard. Thus, the fite VT2S Of ^ contmns 
translations specific to STSC's downloaded character set for die VT220 
terminal. The following tables are available: 

aplotab a translate table fat APL/ASCB. typewrilw-paired 
terminals 

bltotab a translate table to be used with bit-paired 
terminals, such as the HP 2641 A. 

rawotab a translate table that causes each element of UAV 
to be output with no translation at all 

vt220tab a translate table for VT220 terminal wiUi 
downloaded APL characters. 

An output translation file should be a regular VMS sequenli^ 
Stream_LF file containing exactly 2S6 lines. The lines should be 
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delimited by the linefeed character {UTCLF in APL, not DTCNL), as 
would be produced by the VMS editor. For example, the 48th 
character of 0^47 (origin 1) is slash (/), so lto@4S^Ite fil& Siioiitd 

A tiew translate able can be used to chanfe Ae display form of 
characters in APL's 0^4 V or to define display forms for characters titet 
are not presently defined. It does not allow you to define new 
overstrikes that are accepted for input, ^though it can be used to 
control how valid overstrikes are displayed. For example, it can be 
used to control whether characters firom OAV [97] toDi47[122] 
are^tejredas AB£- . .Zotabc.z. 

For convenience, the same notation as is used in termcap files can be 

VE means the escape character (decimal 27) 

Xj means the BEL character (decimal 7) 

\010 means octal 10 (decimal 8), also known as backspace or Ctrl-K 

, V\ naiBans a angle badcslai^ 

Each sequence of cTiaracto should «;tually cause only a single 
character to be displayed on the terminal. If the sequence causes the 
cursor to move anywhere other than one position to the right, the 
t@ffiunal (fisplay iidfl become unsyndBonized mlJi die sessta 

Input Ptoi^Stfbg 

The s^on panrnie^ p roit^t« is used to qiectfy a string fiiat serves 
, a&die APL input prompt. Any string can be used, but the most 

usdiil value is the ASCII BEL character, which causes the terminal to 
' beepwhen input is expected (much like an APL dme sharing system). 

If apearsonal computer is being used as a terminal, the BEL prompt 
caa^povide a useful termination character for a DARBIN-based. data 
tcan^ ia»}tQa{d im ^ PC; for example: 

$ apl prompt=''G 
where. "^G is a notation recognized by APL for Ctrl-G. 
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"Ctemds^g LQgicd Keystrokes" later in this secti<Hi cmtains a 
descii|ption of this notation.) 

ScroUing MemoiyPti^s 
scxeensB 

The session parameter sereeas* i^iieeiGes the niimlber of sosens of 
scrolling memory resorved for die image of the AfL session. For 
example: 

$ apl screens-lO 

^NKifieslNisere^ ll^m^jry is&llocstnedftomtheModcof 

storage reserved for the editor, and it may be necessary to increase the 
editor memory (with the editmem= session parameter) in order to 
haveenoQgli^iaoe. 

Terminal Initialization 

Several session parameters are used to initialize the terminal or specify 
terminal behavior. The status=n is used U> set the initial state of 
insot mode, status line, and keyboard: 

status=0 insert off, status line AH- keyboard 

status=l insert mode on 

status*>2 Stains lute on in APL Session Manager (Default) 

status»'4 text ke^ward instead of AFL keyboard. 

Combinations are specified by the sum of the values fa- the intended 
state. For^cample: 

$ apl status=5 

specifies insert mode on, status line off, and text keyboard. 

Initialization Strings 
tenainit= and tenndinit= 

The session parameter tenninit= specifies a character sequence that 
is transmitted to the terminal upon entry into APL. The default 
sequence is the ASCII character SO (Ctri-N) to switch the terminal into 
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the AM^ character set. The session parameter terHuaiMt- 

a corresponding string that is transmitted upon exit from APL; its 
default is the ASCII character SI (Ctrl-0). The termdinit= and 
^mm^i^ strings aie also mme&B^ when UCMDmd "iCMDate 
used to execute a VMS DCL command ficom APL. 

Both strings can be set to empty, efifectively nullifying the default. For 
example: 

^ $ apl terminit" termdinit- 

Specifying empty strings is recommended on terminals where the 
ir:h. 4S^^ie{il^ produce unwanted ^ects. 

Identifying Ou Tembua toAFL 

. • Thetenninal=paramet«'identifiesthetennindnametoAPL. The 
laininal name will then be used in conjunction with the termcap 



. . • . ■( IF.: ^.TQ-Sfig(|i&a terminal, use the appropriate abbreviation, as in: 




©IPS, 

o200 

hp 

vtlOO 
vt200 

g 

h 



IBM PC running An-*PLUS PC 

HDS Concept 108 

HDS AVT 

HDS 200 

HP 2641 

DEC VTIOO 

DEC VT220andVT240 



generic APL video terminal 
generic APL hardcopy terminal 



', .1 ..ivl:. apl terminal»vt200 



Custom Tema^ 
texmcapa 



The APL*PLUS Syst^ Ux WAX/VMS uses exactly die same 
structure for oitries in the tormcs^ database as are used in die UNIX 
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environmenL The fecility is general enough to enable APL to provide 
effective full-screen control on virtually any CRT display terminal. It 
is possible to develop your own termcap entries for terminals not 
presently included in the atermcap file supplied by STSC. If you 
do, you can specify your own file instead of STSC's atermcap file 
by using the tenncap= parameter, as in: 

$ apl terTacap='fUename 

Since most terminals used in the VMS environment are designed to 
emulate either a DEC VTIOO or VT220, you should ffy identifying 
your terminal to APL as one of these before developing your own 
temeap txiittf and configuration file. See Ai>paidix D for additional 
infcxmdation on the structure of a termc^ database. 

laotimW^otk with a large variety of terminals, the APL* PLUS 
Syst6meat i«cd^^ a setpmce of one w itiMe dharaaets as one of 

the logical editing keystrokes. Many terminals have cursor keys and 
other special keys that transmit special character sequences. 

Each of the logical keystrokes recognized by APL can be customized 
to your terminal's behavior by specifying a session parameter. For 
example, the Cumx^Vlp key on a DEC VT 1 00 tenabial OaifiStQits a 
three-character sequence: ESC, '[', and A'. The cursup= session 
parameter defines die cursOT-up keystroke, thus : 

$ apl CTirsup=\033 [A 

causes APL to recognize the VTlOO's cursor-up key. The phrase 033 
represents die ESC key, which is encoded as octal 033. 

The following table lists the logical keystrokes used in Uiis 
APL ♦PLUS System, the keywords used to specify them on the DCL 
command line in a configuration fiie« and d» MauH diaiact^ used 
for the keystrokes. 
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II^Nng Lo^kal Keystrokes 



I noiml 


* mmm RUE V AVI 






KejTwcMrd 


Ddiaidt 


Enter 






Delete character 


cielete= 


Ctri-D 


riear-EOL 




Ctrl^ 


^^Vl 1 1 1 1 KM m WJi\Ml4A 


c orttmst 


TAB 






Ctrl-F 






rtrl-C 




4- r\nrt 1 aae 


Ctrl-T 




uncio~ 


Ctrl-B 


Alt l/'Air T\«^T1V 

rul-Kcy piCllA 








/Clival A^i'a 






vck V" Q ^ r* ^ Vos 

U V C ^ O U i> X 


Ctrl-P 










k> U >L 0 & A w 


Ctrl-L 




i- \J J. J. \JL\J WAl 


Ctrl-U 


{^iir^or-iit> 




Ctrl-K 


Page-down 




v^tri- V 


Cursor-down 


cursdown^ 


Ctrl-J 


APL-keyboard 


aplkeyb= 


Ctrt-N 


Text-keyboanl 




Qfl-O 


Scioll-up 




Cttl-Y 


O-U-T 


out= 


Ctri-Z 



The defaults apply if no configuration file is used. When APL is invoked 
using the DCL command procedure [ APL . REL«] APL . COM, tfie cmrect 
configuration is selected based on the terminal name you supply. For 
maiiy tenninals, the cursor-movement keys are defined in the atermcap 
&mm^iiwsmi WL ^ \sii^0Mv use tb^ dielibibte, mSk 
omfiguration file need not safipXy them. 

The ASCn characters widl ffiecfatial vdoes in the range 0 ttrough 3 1 are 

called "control characters" and must be represented by a special notation. 
The APL* PLUS System follows conventions for denoting control 
characters either as a l»dt^adi followed by three octd digits or with *^ 
followed by a letter. Thus, the character SO (decimal 14) is represented as 
\ 016 (14 decimal is 16 octal) or as '^N, since Ctrl-N on the keyboard 
jg^P^ dnracl». 
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The logical keystrokes supplied to APL must be selected so each is 
distinct. If the same character sequence is specified for two different 
functions or one key sequence is a substring of another, the message 
WARNING - CONFLICTING EDITING STRINGS appears 
when APL is first invoked. For many terminals, the sequences transmittal 
by the cursor keys are part of the information stored in the termci^ 
database. If so, it is not necessary to explicitly describe the cursor key 
axles in the AFL configuration file. 

The most common source of conflict is the character ESC, which is APL's 
default PF-key prefix and which is also transmitted by many terminals 
when the curscM* keys are pressed. Specifying a unique sequence for the 
PF-key keystroke will silence the warning message. Ctrl-A (decimal 1) is 
a common choice iot the PF-key keystroke in this case. 

1^ Configuration Files 

APL ses^oh parametos con^n iiffttfinadoii {Msvided to APL when it is first 

invoked. These parameters control the characteristics of the APL session. 
Session parameters are specified either in the VMS command that invokes 
AfL or in eoifiguradon files. 

The number of session pieuramet^ you may need to provide is often too many 
totypeiSfWrtOfth&VMSc^iUaiMittatrav^^ TheAFL«PLUS 

System, therefore, provides a means for you to use a configuration file that 
contains an arbitrary number of additional session parameters. 

You can think of a configuration file as an extension of the VMS command 
line that invokes APL. Use the initf ile= session parameter to specify 
the name of the configuration file. For example: 

$ apl initf ile=apl_disk : [apl. rein] pc.init 

invokes APL with the file named [APL . RBLn] PC . INIT as the 
configuration file. 

A configuration file is an ordinary VMS file of ASCII text, that would be 
produced with the VMS editor. Each line of the configuration file contains 

the definition for one session parameter, just as it would be specified in the 
£>CL command line. It is also possible for an configuration file to contain 
comments; any line that begins with "#" is considered a comment. 
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For example, suppose the file [USERXD ] sample . init contains the 
following lines: 



[line 1] # This is an APL init file tteat runs APL 

[line 2] # with a 150,000-byte workspace: 

[line 3] 150000 

[line 4] # and 10 screens of session memory: 

[line 5] screens=10 

[line t] # Bind initial workspace [useridlaatostart : 

[line 7] initialws- [userid] autostart 

Thai the following two VMS commands are exactly eqpii'^tot: 

$ apl initfile= [userid] sample . init 

$ apl 150000 screens=10 initialws" [userid] autostart 

Spee^ying Cot0gmvMon FUes 

The session parameter initf ile= is used to specify a configuration 
file explicitly by name. You can specify more than one configuration 
file, and it is possible for a configuration file itself to contain the 
initf ile= session parameter to specify another configuration file. 
One configuration file cm be linked to another, iq) to a maximum of 
15 files deep. 

Whenever the initf ile= parameter is encountered, the effect is as if 
die contents of the specified file replaced die initf ile= parameter. 
If a session parameter is speci&eA m&t fhun &mi it@ lait d^ition is 
the one used. Thus, the defect of: 

$ apl initfile-[userid] sample. init 50000 

is to run APL with a 50,000-byte workspace, even though the 
configuraticm file specifies 150,000 bytes. 
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Chapter Two 

Editing Functims and Vmiables 



This chapter describes thti two editors thatare available in the 
APL*PLUS System: 

• a full-screen editor that can handle functions, characta variables, 
and the record of your APL session. 

• the traditional APL function editor, known as the del (v) editor, 
wluph is line-oriented and (mly i^plicable to us^-defmed fimctic^ 

Section 2-1 of this chapter describes the full-screen editor and its 
associated ring of multiple images undergoing editing at any given 
time. The descriptions IncMe the ccoicept of the edit ring and iis 
usage: placing a copy of an object from the active workspace in the 
ring, moving between images (including your APL session and its 
immediaie oscudoB i»odie^, at^rb^ «»Win the image m Urn 
and off, diaii^sig itae inaage, and redefining an oi>ject jtom ^ inia^ 
the ring. 

Section 2-2 of this chapter describes the del editor and its associated 
function definition mode. The descriptions include entering and 
leaving function defmition mode, and selecting, displaying, altering, 
editing, or deleting individual lines of the function. 

2-1 TheFull-Screen Editor 

The full-screen editor is the pari of the APL ♦PLUS System that 
manages the input and output between the user and the APL system. 
The full-screen editor includes a program called the Session Manager 
that conDt)ls what appears on the terminal screen. Bemuse the Session 
]^^^ and fidl-screen editor are one unified program, you can edit □ 
' wi W^mt and output, and □ VP UT output, as wdl as AFL 
functicxis and data. 



I. . 
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Using the Session Manager/editor, you can: 

• create or modify functions or variables in the active workspace 

• edit several objects at the same time 

• edit the image of the APL session and save text into functions and 
variables 

• use cursor movement, scrolling, and paging 

• insot and delete characters 

• copy , move, and delete blocks of text 

• move blocks of text between functions, variables, and the session 

• search for specific charactasequfflices and optitxially replace thm 
with another string 

• switch to text mode to allow entry of ASCII text (upper- and 
lower-case letters, characters such as #%&", and so on). 

4 Bing EMng Images 

The full-screen editor operates on visual images of APL functions or 
variables. The editor can work with many images at the same time, 
although only one image at a time can be displayed on the terminal. Each 
image is stored in a logical screen that has a name and a unique screen 
number. A logical screen exists outside of the workspace where actions 
like ) LOAD and ) CLEAR ionotaS^tiL 

The screen images stored in the editor are arranged in a ring, like a rotating 
desktop telephone card file where many cards are stored but only one is 
visible. You can move freely from one image to another without losing 
its contents. Commands are provided to create new screens, move between 
them, delete them, and define functions or variables from th^. 
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Changing the image of a function or variable &l fh& &&m Im no effect on 
the object in the w(»jcspace until the image is explicitly written back into 
-jT f:. the workspace. 

The ARU sessiiHi is simply one of the images in the edit ring. Editor 
coounaDds can be used <m the APL session, providing some very useful 
capabiliti^. Fbr example, you can develop APL statnnenfs interactively 
in the session, then copy the lines of COde into the image of a function 
being edited. The string search feature can be used to find a Une of text in 
die AHL session. You can evra write the session image into the 
workspace as a varialde. 

. SpfcMiBehavior oftkt APL Session Screen 

There are three main differences in behavior between worlcing in the sessioi 
screen and editing a Amction or variaUe: 

• The response to the Return key is different. In the APL session 
screen, pressing the Return key causes APL to read the current line 
as input and act upon it. When editing an object such as an APL 
function, pressing Return simply moves the cursor to the beginning 

. ..... ...oftben&ttline. 

• The maximum nuttber of linra presmed in the APL session screen 
is fixed when AFL is invoked. The default maximum is four 
terminal pages, but you can use the startup parameter screens= to 
^ed^ a larger maximum {see Seeticm 1-7). Onee all ^ lines are 

used, the topmost lines are discarded as new ones are appended. 
When editing a function or variable, however, data is never lost 
TNew lin^ areadded to the object as it grows, limited only by the 
amount of memory allocated to the editor at the start of the APL 
session (see Section 1-7 for information on the editmein= 
paiaroeter). 

• Line numbers can be displayed in edited objects but not in the APL 
session scie^ 
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Status Line 

The last line of the terminal screen is reserved for a status line which 
contains information about the active screen and keyboard input state. 
The status line can be switched on and off using Command T 
(described lata: in this section). Heie axe some examples of status 
lines: 

SCREEN 1:APL SESSION Ovs APL 
(The APL session screen.) 

SCREEN 2: FN READ Ins APL 

(An APL function named READ.) 

SCREEN 3:CHAR MAT PRICES Ins Text 
(A character matrix PRICES.) 

The status line consists of three fields: 

• the screen number, which uniquely identifies the logical screoi. 

• object identification, which identifies the object in the screen; the 
field will contain APL SESSION to identify the session screen; 
for other screens, it will contain the designation FN for an APL 
fffiieion. &t CKAR followed by VEC eg HAT to identify a character 
vector or matrix, followed by the object name 

• editor state, which contains the indications Ovs for overstrike 

mode, Sep for replace mode, Ins for insert mode,orCmd for 
command mode; APL indicates APL font keyboard and Text 
indicates ASCII text keybosffd^puL 

Full-Screen Editor Commands 

Ftill-screen editor ccnnmands can be divided into two classes: 

• basic iaiid ft«quen%isedeommands such as "'move the cursor up 

one line," "untype the last character," or "start insert mode." They 
are typed with single keystrokes. These keystroke commands 
include Un^rpe, Delete, Undo, Ovostrike, Gear-EOL, and 
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keystrokes for cursor moveao^t imA wiiiddw scipUtog. Th^ are 
. lUtedinJectjoa 1-5, 

. r . • ipewerful and general comrnands such as ''replace one String with 

another," "delete five lines," or "delete all characters through the next 
' 0 ' . " These commands are formed starting with a prefix key and 
. gcnexaUyiequiEeraiilttplekeystn^. 

General Full-Screen Editor Commands 

General commands all start with the Command keystroke (usually the 
TAB key), which tells the editor that the keystrokes that follow are 
. li. .1 •jpart of a command and not APL input. Most of the commands allow 
> ' an optional count or repetition factor and a modifior or arguments. 
' ' 0 . Here are some examples of general commands: 

TAB 10 4^ . (Move the cursor to absolute line number 10.) 

TAB 6 D SPACE (Delete6chaiactmtotherig^t.) 

' - ' TAB 4 D RETURN (Delete 4 lines.) 

In these examples, the Command prefix is the tab character, the 
default However, you can use a different keystroke as the Command 
key. Section 1-7 explains how to specify the keystroke. The words 
SPACE and RETURN represent the terminal's space bar and Return 
keys. Spacing between the daracters of the command pixmdes clarity 
in the example; the spaces would not be typed in the actual command. 
Likewise, brackets, used to indicate fields that are optional, are not 
typed in Id ^Misti^Qmniand. The giaie^ fonn of an edi^^ 
command is: 

"if^lamntlmmiepcawneters 

The count is typically optional, and parameters are not needed for all 
commands. ' - 

If you.press the Return key to end a command, the word RETURN 
: ' .^-i^yKiaFS in the description. Many ccnnmands do not require you to 
press RETURN; they are completed as soon as you have typed the 
entire command. The characters used in commands assume the APL 
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fceyboard; for example, TAB E means the TAB key followed by the 
unshifted E key. 



Commands for E^ttg Functions and Variables 

The following commands are used to control the contents of the edit 
ring. Commands aie provided to create a new logical scteea, to move 
ftom one screen to another or back to the APL session, and to define 
APL objects from their screen images. 

Eidit object tab E neme [options} return 

Cresoe a togical screen contaimng an kmig^ of theBBUKsd objei^ and 
display the image on the screen for editing. The name of the screen is 
the same as that of the objecL 

Igrite Object tab V [name] [opdonsj return 

^te a copy of the cmroit logical screen into the active woricspace. If 

a name is specified, the object is given that name; otherwise, the name 
from the function header or, for a variable, the name of the screen is 
used. 

Exit editor TAB Z [name] loptions] RETURN 

Write a copy of the current screen into the workspace (as name), delete 
the screen, and return to the APL session. This command is the quick 
way to exit from the editor. 

Quit editor TAB Q [ALL] RETURN 

Delete the current logical screen and return to the previous one. If 
ALL is specified, all screens except the APL session screen are 
ddeied 

fiet object TAB G RETURN 

Get the object (name) from the workplace and insert its image at the 
current location in the screen. 
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£0Fward screen 



•SRB F [name] RETURN 



Move forward lo the next logical screen or, if name is specified, to the 
serera -witl) that name. 

backward screen TAB B RETURN 

Move backwaid to the j^vious logical scre^ 
APLfiess^n screen tab 5 RETURN 

Move to the APL session screen. 

I>i^Iayfibg tab R 

Disiday the contents ctf the ring of logical sdceeos. The talte of 
: contrae ronains visible until you press Return. 

' '1^he&/Mf9iufi^ in the above cafiflmodSctuie^ 
the following q)tions, as apimqniate. to specify the ^pe and rank of 
the object: 



-FN edit or write the object as an APL function 

-CHAR edit or write the object as character data 

-VEC edit or write the object as a vector 

-MAT edit or write the object as a matrix 

-LNO edit the object without line numbers 

-iiNl edit the Object with line numbors (default). 

When you begin editing an object with TAB E, the default object 
type is that of the object, if it akeady exists. If the object does not 
eixist, the default type is function (-FN). When you write the object 
back to the workspace (tab V), it wQl be stored as tte same ^jigct 
type as it was in the editor. 



Note that changing the active screen with edit (tab E), forward 
(TAB F), backward (tab 5), or session (TAB S) does not 
desctoy die current logical screen. The current screen becomes 
inactive, and you Ctti return to it by moving around the edit ring. 
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In additon to the basic cursor movement keystrokes, the following 
coinnmds can also be used to move the cuisor around die screen and 
to scndl and paf0 (|> and domi: 



Pseudonym Keystrokes 

TAB H 



Bottom 

Top 

«*- 

n — 

Down 

Up 

Scroll t 
ScroUi 
Page t 

Pa^ i 

Locate-* 

Locate n 

Locate ♦- 



TAB L 
TAB J 
TAB K 
TAB n H 
TAB n L 
TAB n J 
TAB n K 
TAB n Y 
TAB n U 
TAB n C 

TAB n V 

TAB X c 

TAB n Xc 

TAB X C 



Result 

Move to the left margin. 

Move to die right end of die line. 

Move to the last line of die logical screen. 

Move to the first line of the togical screen. 

^fove n spaces to die left 

Move n spaces to die ri^L 

Kfove n lines down. 

Kfove n lines up. 

Scroll the window up n lines. 

Scroll the window down n lines. 

Page die window up n terminal screens. 
If n is (xnitted, page up one screoi. 

Page die window down n terminal screens. 
If n is onunitted, {Ktge down one screen. 

Move right to die character c. 

Kfove right to the nth occurrence of 
character c. 

Move left to the character c. 
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Locate 0 n 
Jump 



TAB « 

TAB n 0 
TAB 0 C 



^^Sm^* TAB n .A 
Commands for ifele^g Chaneters 



Move left to the ndi occanaice of 
dmaciac. 

Move right to the next diamond. 

Move right to the nth diamond. 

Move to the line marked with the letter c 
(see "Marking a Line," below). 

Move to absohitB line number n. 



You can delete multiple characters with the delete command. Each 
ten of tfie command takes an optiraial number which d^aults to 1 if 
' oniOfid. ' ' 

Delete tab n B L DidteteA^aniGiecstottei^tt. 

or TAB n D SPAilllE (Altemaie fixm above command) 



Deleter- 
Delete n 

Delete «- n 



TAB n D H 

TAB n D X c 

TAB n D X c 



Delete n 0 tab n D 0 
Commands for Marking a Line 



Delete n charactos lo the left. 

Delete right to the «th occurrence of 
dKuacterc. 

Delete left to the nih occunence of 
ciiarat^c. 

Delete right to the «th occurrence of 0. 



A line can be marked with any one-letter name for reference in other 
ctxnmands. Once marked, the line can be referenced by the 0 modifier 
followed by the character. For example, TAB 0 A moves the 
cursor to the line madced widi letter ^. 



Mark 



TAB M e 



Maik the cunm line wiA character name c. 
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Commands for Deleting and Saving Lines 



One or more lines can be deleted from the logical screen with a single 
command. The deleted lines are saved into a buffer and can be insoted 
from the buffer into a different place in the logical screen or even into 
a different logical screen. Lines can also be saved into the buffer 
without deleting tiion. Onfy one poop of lines is saved in the buffo^ 
at once, so deleting or saving a block of lines causes the {xevious 
buffer contents to be losL 



Delete i tab n D D 

or TAB n D J 



Delete n lines downward, including the 
line on which the cursor appears; default 
number is 1 to delete cunent line only. 



Delete t 



TAB n D K 



Delete n lines upward. 



Delete TAB n D A 

Block 



Delete from current line upward 
(positive n) or downward (negative n) 
to line number It; tf it is tmsjii^fled, 0 
lines to the l^t line in the logical 
screen are deleted. 



Delete 
Thru 



TAB D 0 c 



Delete diiough line naarked with letter c. 



Ciqiy I TAB n *- -- 

or TAB n J 



Save n lines downward into the buffer, 
including the current Une. Note that *- 
rq)resaits the AFL assignment arrow, 
not the cursor-left key. 



Copy t TAB n *-K 

Copy Block TAB n A 



Save n lines upward into the buffer. 

Save from the current line to absolute 
line number n; if n is uraipeclffiGed, all 
lines to the end of the logical screen are 

saved. 



Cq)yMark TAB *- 0 c 



Save from the current line to the line 
marked with letter c into the buffer. 
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Comnmtub^r tmenbig^/imand Saved Lines 

New lines can be inserted with tte insert line command. The lines 
saved in the save buffer (firom delete or copy) can be insmed with 
put command. 



Insert 1 Insot a blimkinebt^ow the current 

Uttf I line. 

Insert TAB I Insot a blank line above the ciBrent 

Line t line. 

Put I TAB P Put the contents of the save bu£E» 

bdow the current line. 

Putt TAB * Put the contrattsctf the save buffa: 

above the cunent Une. 



Note that moving from one logical screen to another with edit (tab 
E), forward (tab F), baclcward (TAB B), or to session (tab 
S) does not alter the omteacscf die save bei^. Copy and put can 
be used to||pe:|ine$ between fimctions ot finom the session to a 
function. 

Comnmntbfer SpUMi^ aa^ Joining Lines 

Join TAB , jynAenextlinetothecncrmtUneto 

form one line. 

Split tAB . Split the cuirmt line at Ae cursor 

position to make two lines. 

Commands for Searehtng awlRepit^ng 

The search and replace conunands are used to locate a sequence of 

ehaffaeiers m a screen and ^ddodl^ le^teise it wtdi a 

String searches wrap around to the Start of the togical soeoi if the end 

of the screen is reached. 
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TAB / String KEHmU 



Search the logical screen for the next 
occurrence of string. 



Repeat 
Search 



TAB / RETURN Repeat the last String search command. 



Replace n tab ii \ \ slring2 RETURN 



Replace 



Replace 



Change n occurrences of the search 
target from the previous suing search to 
the givoi string!. Default n is 1. 



Replace All tab $ \ \ string2 return 

Change all occurrences of the search 
target from the previous string search to 
the givoi slring2. 

Repeat tab space Rqteat the previous string replace 

Replace command 



TAB n \ L Jtrjng2 return 



Delete n characters to the ri^tand 
replace them with string!. 



TAB n \ H string! RETURN 



Del^ n characios to die and replisce 
Aem with string!. 



Replace 
Mark-* 



Replace 
Mark«- 



TAB n \ X c string! ^TVHN 



Delete from the cursor to the nth 
oectBimce of character c ^ refilace 
with string!. 



TAB n \ X c string! RKHmm 
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Etelete hom die (Mrsor left Ate nth 
occurrence of chaxactet c and iqdace 
with string!. 



Replace 
On 



TAB a \ 0 stnng2 return 



Ddetefi^ the cursor to the nth 
occurrence of ' 0 ' andreplace with 

slringZ. 



Miscellaneous Comnmnds 



Sitatns 



TAB T 



llim the Status line (» and off. 



Help 



TAB ? 



Display the help screen and allow the 
user to browse through a list of ediUK' 
conunands. 




Any general editing command can be canceled before it is completed by 
v^peatii^ ^ Command ixefix; fiw exanqrie, 

TAB 5 D TAB 

This command, which was intended to delete 5 lines, does not take 
effect because it is terminated with Command. 



There is a command mode in which all keystrokes are treated as editor 
commands. In this mode, the command prefix can be omitted in all 
eonimands. This mode is useful for editing an existing objiset, 
moving data around, making global changes, and so on. As an 
example, the commands to move to line 7 of a function and delete 3 
: tei niiimailly would be: 



Command Mode 



TAB 7 A 
TAB 3 DD 



2-13 



Editing Fimctioiis mi Van jjbles 



In command mode they would be: 

7 A 
3 DD 

Command mode overrides insert mode and overstrike mode. Characters 
typed in during command mode do not become part of the text. 

TAB X Switch in and out of command mode 

(the keystn&e is the APL multiply key). 

Entering the insert hne command from command mode temporarily 
returns you to insert or overstrike mode to enter data on the new line. 
As soon as you leave the new line with any editor command, you are 
back in command nxxle. 

Editor S]^tem Commands and System Functions 

The system ctmtnand ) EDIT and system function UEDTT invoke 

the full-screen editor and have the same effect as the TAB E key 
sequence. The system command ) HEL P is the same as TAB 7 . 

U^g Hardcopy or Limited Termbials 

The features of the editor are available on any CSJ tmBasgi witfi a 
minimum set of capabilities. The minimum functions required to 
support a terminal in full-screen mode are : 

• clear to end of line 

• clear screen (or alternatively, dear to end of page) 

• cursor addressing (or alternatively, home-cursor). 

Most CRT totminals have at least these faciiiiics. If the terminal has 
more advanced feauu'es than these, they will be used, but they are not 
required. The trnmhial need not have any cursor control keys or 
function keys, but if it does they can be used. Information on how to 
conuol the terminal is extracted from the termcap database. For further 
infit»naiiira on teaacsp and AHL's use of it, see Section 1-4 and 
Ai^ndix D. 
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The APL*FLUS Syston wiD ftmctitti wilfi handeopy terminals and 
terminals without the minimum set of features, but editing capabilities 
are limited. In these limited terminals the system works in line mode, 
and none of die gwmsH Mi-^cteea editor commands can be used. The 
system commands ) HELP and )EDIT and the system fiinction 
OFJilT are disabled, but some of the basic editor commands can be 
0^. these prav^ wet i>dfh ba^ editing mpMi^ UiEe ttose 
used on earlier APL system implementations. In line mode, the 
following editing keystrokes can be used: 

Un^rpe Wodc as backspace followed by linefeed. 



Delete Work only on the last dMraefO' of the line; 

the visual effect is a linefeed. 

Oear-EOL Erase aUchaiact»s£nHn die «wsorio the 
end of the line. The visual efkct is a 
linefeed. 

BxiBt Enter die current line as input to APL. 

Cursor-down Move die cursor down one line. 

Cursor-left Move the cursor left one space without 
erasiog is dtore (non-destructive 
badopace). 

Curs(M--right Move die anscir t|^t <m sgms widiout 

oasing what is tbore (non-d^tructive space). 

Undo Discaidevesrydiing typed on die line and 

le-jHompt 



BttiofEwors 



An incorrectly formed editor command will produce a warning to the 
user by flashing the terminal screen or sending a bell chaiactrar. This 
may occur when you try to delete more lines than a screen contains, 
when you try to fiHin an illegal overstrike, or from a variety of otho' 
circumstances. Additionally, the editor may produce the following 
ems messages: 
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CANNOT GET UNDEFINED OBJECT 



The object requested does not exist in the woricspace. 

CANNOT QUIT APL SESSION 

The quit command (tab Q) is not valid from the APL 
session screen. 

CANNOT REPLACE FN VITH VAR OR VAR WITH FN 

The write command (tab V) was issued to write an object 
as a variable when it already exists as a function in the 
workspace or vice versa. Use the session command (tab 
S) to move back to the session to erase the object and the 
forward command (tab F) to get back to the original 
screen to retry the write command. 

DEFN ERROR 

An error in the structure of the function prevents the 
function from being defined in the workspace. 

DOMAIN ERROR 

The object of an edit command (tab E) is not m sSkmslbh 
datatype. Numeric data, nested arrays, and heterogeneous 
data cannot be edited. 

HELP FILE NOT FOUND 

A help command (tab H) was issued and the help file 
cannot be found. The default help file is 
FAPL.RSLnlHEif .RLP. Alternate he^ fites cm be 
specified with the help= session parameto'. See Section 
1-7 for details. 

IMPROPER NAME 

An edit, get, fonmrd, or write command (tab E, tab 
G, TAB F, or TAB V) was issued with an improperly 
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fonned variable or function name. Names must be 
well-fonned APL identifiers. 



INCORRECT OPTION TO QUIT COMMAND 



The quit command (tab Q) was used with an option cxhex 
than ALL. ALL is the only option allowed with the quit 
command. 



LEUQTH ERROR 



The edit or get command (tab E or tab G) was issued 
fora mahix diflt has a seconddimeBSicm peai» tfian l^^^ 
- ~ or for a vector that has m(He than 1014 chaiactns between 

newhne characters. 

LINE TOO LONG 

'niej(rinarce|>l^oomBBaad(¥£B , (irT%B \)tesDed 
would have resulted in a Une of more than 1014 characters m 

length. 

NAME MISSING 

" An edit or get command (TAB E or TAB G) was issued 

without specifying the name of the variable or function to 
beedited. 



NO PREVIOUS CHANGE 

' A repeat replace command (TAB space) was issued 

" ■ when there is no last change to repeat 

NOT ENOUGH MEMORY AVAILABLE 

The edtor has ran out of memory and einnot perform the 
requested operation. You can delete an unneeded logical 
screen from the edit ring by moving to it and using the quit 
command (TAB Q). If this pxjblem occurs in the delete 
command (TAB D), it is because the editor is attempting to 
save the deleted lines so you can later retrieve with "Undo." 
Try deleting fewer lines at once. The memory allocated to 
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the editExr can be increased or decreased with the edittnem'^ 
paiameter at APL startup. See Section 1-7 for details. 

NOT FOUND 

The object of the search command (tab /) was not found. 

OBJECT ALREADY EXISTS 

The write command (tab V) was used to rename an object, 
but an object with the new name already exists in the 
workspace. Use another name or return to the session with 
the smkm command (tab 5), oase Ae object, and return 
to the edit screen with the forward command (TAB F). 

ONLY IN IMMEDIATE EXECUTION 

During □ or □ input, an edit command was issued that 
would move to a new logical mem. This is allowed only 
during immediate execution mode input 

RANK ERROR 

The edit or get command (tab E or tab G) was used to 
edit an anay of more than two dim^iqns. 

SI DAMAGE: WRITE IGNORED 

The write command (tab V) was issued for a function 
which has been altered in such a way as to affect the 
localization of names in the header or the line labels. A 
version of the same function is suspended. Use the 
session command (tab S) to move back to the session to 
clear the suspension and the forward command (tab F) to 
get back to the original screen to retry the write command. 

UNKNOWN OPTION 

An undefuied option was specified in a command. 
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UNKNOWN WRITE OPTION 



Aji undefined or invalid option was q)ectfied in a write 
command (tab W). 

UNNAMED OBJECT - SUPPLY NAME 

, A write command (tab I/) was issued for the APL session 
screen without supplying a name. A name must be 
specified fiv diis case. 



This section describes the del editor, a traditional line-oriented function 
ediiKM'. Topics covoed in tiiis secticHi include how to: 

• ^ter and leave fiinction definition mode 



• understand tiie prompt 

• select a line of tiiefimction(widi [ ]) 

■ display the function or a line of the function for posaNb editing or 
iq)laeemait(witb □) 

• delete selected lines (with ~) 

• enta or edit a selected line 

' exitfiom the editcv, leaving the function unchanged. 



To enter function definition mode, you must first be in immediate 
execution mode (that is, the system has typed a prompt of six spaces 
9iidsi»SMdiiiigyourmput). Ilien: 




Entering Function Definition Mode 
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• Typeav. 

• Type a function name (IfAMM is used in die discussion below). 

• Press Enter. 

Places ^sce vffliations are posabte are indicated by dots: 

V . . . NAME . . . 

To create a new function called NAME (when there is no function or 
variable called NAME in the active woricspace), ento: 

V RESULT LEFT NAME RIGHT 

This creates the new function, and establishes its syntax by using this 
line as the header Une. Any of the following can be omitted, thaeby 
establishing a different syntax for the function name: 

RESULT 

LEFT 

LEFT AND RIGHT. 

Thus, V NAME can create a new function called NAME that talces 
no arguments and yields no explicit result. 

To re-open an existing unlocked function called NAME that is already 
present in the workspace, eater. 

V NAME 

Regardless of the syntax of the function name, the system will prompt 
for a new line at the end of the function. 

Leaving Function Definition Mode 

To l^ve fioQcion ^tsMm mode, aid My line with a v md press 
Ent». Alternatively, using v will lock the fimction. 
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' ' Hie iE^feces of leaving function definition mode are: 



• The lines of the function are reordered according to their line 
/ ' ^ i^a^l^. The header is treated as line 0. The other lines are 

t-ai.., J.., .a , -1 renuttflwed with consecutive integas, if necessary. 

KS'^i^ 90} 0* « l)i-. ,1 ■ ^ 1. • . 

• The current header, if differmt tm tte odi^sd hesto« dneaffliaes 
' '^iteeaiidi^iffiiforsubsequratiiseofihefimction. 



• The function is lodced (can never be redisplayed or edited, but can be 
oased) if a V was used what entering or leaving definiti(m mode. 

• If the function being edited was suspended (noted in the state 
indicator with a *) and the renumbering has changed the value of 
labels, the new values will s^ply when execution is resumed. The 
ertor message SI DAMAGE indicates diat the editing changes 
wiUnot permit ihe function to be restarted. The damaged levels in 
the State indicator are indicated by [ ~ 1 ] in) 51. Entering 

i RMSET wifl^dear die damaged state indicant wd tbe newly 
edited fimction can be run. 

• proiitpt Sir iBtWislte ©iiseation mode leplsxs the 
sqfsm^mAisted prranpts ctf definidoi mode. 



IXseariBng E(Mtm- ChmgK 



If you change your mind and want to discard all the changes you have 
made in fitmction de&iition mode, you can exit firom the editor by 



in les^nse to the numbered prompt. The system displays the 
message f^XT AfOfiTfD.andtheorighialformof thefimcticm, if 
any, is restcKed. 



Prompts ^Di^MUottMoire 

A fionction definition is a numbered sequence of lines, each containing 
' ' an APL statemoiL When cHs^tayed, tm fiflesioie ^own m orda*, each 
proceeded by die Une numba OKlosed in square brackets ( C ] ). 
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The piompt in ftmclton d^tniita mode is also a ftmction line number 
enclosed in square brackets; it is the number of the line where the 
system expects to store what you type. The complete prompt also 
inchides the curstv fai the seventh edumn of the saitte Une, waiting for 

your input. Note that if the line number is long (such as 
[1234.567]), the cursor is displayed farther to the right. 

Selecting Function Lines 

To sdect the function line you want to ent^, edit, or delete, specify 

the line number in square brackets and press Enter. You can use such 
a line choice to override the prompt just printed or to end the line you 
used to^ts ddlni^ mo^ lli^ system le^p^ads 1^^]^^ 
the infonnati(m to be stored undo- that line number. Fotexmj^: 

V0LDC5] 

C5] 

Bisfiaying Function Lines 

The symbol □ , used within square brackets, causes the lines already in 
the function definition to be redisplayed. 

[□] Displays the ouiie function as cunratly defined. 

[ Dn] Displays the function from line n through the last line of 
the function (or until you press Ctrl-C). 

CnD ] Displays the line numbered n and prompts for a replacement 
(You can override the prompt, avoiding replacement by 
tyinng a differait line number within brackets.) 

CrDc] Displays the line numbered n for possible editing, leaving 
the cursor in column c. If a zero value is entered in c, the 
cursor is displayed at the end of the line. 

Deleting Function Lines 

To delete a line from the existing definition of the function, precede 
thelinenumba'witha'«' amdeQicit^ gentry in iteacke^. Bss 
example, [~12] (followed by Enter) in refuse to a definition 
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mode prompt completely raBdV^titettaestiMed as Iftie C123. To 
■ delete several lines at once (even lines just inserted between others), 

type ^ ~, type the line nuinbers to be deleted (separated by a space), 
and ^cldse the entry in brackets; for example: 

[~4 5 12 15 8 3.5 3.6] 

The same technique can be applied in a Une used to enter or leave 
definition mode (or used to both enter and leave definition mode in the 
same line). Fw example: 

VNAMEL~2 9]v 

enters definition mode only long enough to delete the second and ninth 
lines after the header Of the function name, then leaves definition mode 
and reprompts for immediate execution mode on the ni^t line. 

Entering or Editing Function Lines 

Once the line has been selected (and possibly displayed), all of the 
single character editing actions are available for adding new material to 
' ttfe'^e or changing new or old material in the line. This is erne 
regardless of how the line was selected, how it is di^layed, and 
whether or not the Une number is an integer. 

Even the number of the line can be changed. In this case, both the 
line with the old number and the line with the new number will 
' lem^n.' 

While in function definition mode, you can edit and re-enter any line 
di^layed on Ae saeea. Typically, die st^ are : 

• Move the ciu^r to the already displayed line . 
Ih: • Edit the line, 

• Press Enter. 

ComMnMgFunetiott Lines 

It is possible to combine most elements of definition mode into a 
single line. The following examines slww sev«al of the combined 
actions you can use: 
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vSESULf*-LEFT NAME RIGHT ; LOCALl ;L0CAL2 

[1] L0CAL1^2>'LEFT 

[2] L0CAL2- pRIGHT 0 RESULT - L0CAL2 + LOCAL! 
V 

to the above example, only the line number prompts [ 1 ] and 1 2 ] 
were typed by the system. The first line enters definition mode, 
creates a new function with two arguments, two local variables, and an 
explicit result The second line enters a first line for the function. 

When the system prompts for the second line, the user entos a line 

and ends it by leaving definition mode. 

9NAME 11. 5} RESULT *- RESULT + p RIGHT 

7 

The example above enters definition mode, inserts a new line between 
lines Cl] and [2] , and leaves definition mode, eausingienunbering 

of lines. When the function is redisplayed, the new Une is line [ 2 ] , 
and the numbers of the following lines are all one higher than they 
were before. (This is an important reason for nsilif MneU m tines to 
which you want to branch within the function. If the function is 
subsequently revised, line numbers may change, but the labels remain 
with the intraided destination line.) 

To redisplay the function without staying in definition mode, enter: 

If you enter the statement: 
vNAMELQ} 

the system displays the entire function, stays in definition mode, and 
then prompts for a new line to follow the last line of the function. If 
name not tfie NAME of aa existing function, Ae system reports a 
DEFN ERROR is reported. Entering the statement: 

7NAME 13U1V 

displays line [ 3 ] and returns the system to immediate execution 
mode. 



Copyri^ 1$87 foe. 



2-24 EditSag F^edotis mi Variables 



skips the header and lines [1] and [2] but lists the remainder of the 
. iunctioa and dun leaves definition mode. 

If you omit the final v in the last example, the system stays in 
fimcdiiiti^dififfigiHi f^lie and f8«om^ for entn' of the Aext function 

line (one plus the highest line number). You can either enter 
information for the new line or request redisplay of an existing line. 

[12] [3n7] 

redisplays line [ 3 ] with the cursor in column 7. You can then insert 
additi(xial information at the beginning of line C 3 ] , possibly 
sqiaraied fixmt die ffldsting statemoit with a <>. 

Error Reports in Function Definition Mode 

DEFN ERROR 

One oS the foUpwmg has occtuxed: 

■ An mcorrectityfonned header was used. 

• A line was entered that does not begin with a square-bracketed hne. 

• A V not in quotes or in a comment occurs witiiin a line. 

• An mempt vm made to delete the header, to define a fiineticm with 
die same name as an existing variable or label, to re-open definition 
of an existing function by specifying something other than the 
fim^iiminQie after die v, to ofiai a locked function, or to open a 
pendent function (use □ 75 to see it). 

51 DAMAGE 

You have closed definition after making changes to suspended or 
pendent functions that invalidate the current suspended state indicator. 
The state indicator must be cleared before ^ecution can be restarted. 
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SI DAMAGE PENDING 



You have made changes to a suspended or pendoit function that 
invalidalB the cunent suspended s^ indicates. You can tecovex at this 
point by canceling the changes made using [-»]. 

SI WARNING 

You are opening definition on a suspended or pendent function. 
Chaining die syntax or bbels of a suspended fiinction or making any 
diaqges to a pendent function will damage the suspended state 
iiu&^r. However, other corrections to a suspended function are 
permidBd. 

WS FULL 

There is not enough space iii the active workspace for the fiunction 

being defined. 
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Chapter ^hree 

Using Files with APL 



The APL*PLUS System for VAXA'MS, like other APL*PLUS 
Systems, gives APL the ability to store and access data in disk files 
outside of the APL workspace. As a result, you can use the flexible 
' sharing capabilities of the APL * PLUS System's conywnent files in 
conjuction with other types of files native to the VMS operating 
system environment With these capabilities, your VMS operating 
Sys^m becomes an excellent environment for multi-user (shared data) 
AI%«;i^tications. 

- f! . : < The following general capabilities are available with the APL*PLUS 
" ;xi System's disk files: 

• the ability to enter, retain, and access data in disk files, where the 
I i, V', . • daaiKta teriMfafla- ttie APL session ends 

• ' ? the abilir|r to store more data than can all fit at a time in the APL 
-rr : < , :tw@rfE^^e dnd to lebieve it in mara^patble p^ons 

• the ability to perform file operations (like creating, erasing, 

- ^sqp^raiding to, mid renaming a file) under program control 

• the ability to usp native VMS files from APL, providing an 
intoface b^em ABL mA APL programs such as database 
managers, woid processors, and spreadsheets. 

How This C^ptitf ts Organized 

- Section 3-1 introduces files in the APL*PLUS System; it defines 

. fflesj C^ovm the fundamentals of file use, and describes the minimum 
set of file op»atu)ns needed fo' worldng witti files. 

Section 3-2 explmns ^didonal file operations useful fbr msmagfaig 

personal (nonshared) files. Sections 3-2 and 3-3 together describe all 
the file operations needed for personal file management 



Section 3-3 introduces file sharing. File operations are discussed that 
allow both casoalpeEsooal ©esfaange of files and information and 
formal, regulated access to a common information base. 

Section M (Qscusses deadledi mmoA of fite access. It is intended for 
individuals who will be implonenttng major q>plicati(His that require 

the use of shared files. 

Section 3-5 discusses the access matrix in more detail and explains 
how to apply it and the effects of making changes to it. 

Section 3-6 explains how the APL*PLUS System relates the VMS 

directories to APL librarKS. 

Section 3-7 compares the APL compcmoit files and the native files 
available through the APL* PLUS System. 



3-1 Fundamentals of File Use 

The APL* PLUS System includes a built-in file system for the APL 
environmenL This file system allows easy use of either floppy disk 
drives or hard £sk drives to store da^ either in APL component files 
or odier file types native to the environment You can store, retrieve, 
and otherwise manipulate data with APL system functions. 

KeyConce^ 

The matexitd in fiis omM piesinnes 0iat you have a clear 
undersunding of sever^ key concq>ts: 

files: A file is a place for storing aid organidng data in permanent 

disk storage. The APL* PLUS System uses two distinct kinds of 
files: (1) APL component files, which are used to hold APL arrays, 
«9d (2) native files, which are standard to tte VMS cpefadng sy^an 
enviroimient 

APL componeiit ffles; An AFLfite isstmetnnidasasetof 

components, each of which contains one APL array. An APL file 
component is much like a variable, except that it has a number instead 
of a name. Any value that can be stored in a variable can also be 
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stored in a file oM^XK^t Theflle^MiqpcmmteiMitafaiscdinplete 
mfitniitiatidii about the AFL array, including its siu^ and data^^. 

' iitttivefflte^ These are VMS sequential Streain_LF files, of the 
fomused by the VAX C run-time library. The APL*PLUS System 
tKxOi native files as simple sequences of characters (bytes of data), 
leaving the programmer responsible for any structuring and 
housekeeping. Native files provide a means for APL implications to 
share data with non-APL applications. 

directories: The VMS operating system organizes files using a 
liierarchy of directories. A directory is a special kind of native file that 
contains a list of file names. The names in the list can be files or 
other directories. Any file in the system can be located by ^edfying 
)i^&WSetoty in which it residies. Every user has a de^ult ^rectasy 
whoe files and workspaces are stored and sought if no directory is 
ejqriidtly named. Users can also create and access files in odi^ 
directories explidfly referring to the diiecuvy in a command. 

libraries: Traditional APL systems organize files and workspaces 

idiratified by numbers instead of names, and they are not hierarchical 
(that is, a library cannot contain another library). The APL* PLUS 
System provides a mechanism for simulating traditional libraries by 
associating a library number with a VMS directory. This allows 
*" ' ^plications that were developed on other APL* PLUS Systems to run 
withcttt-ttiodifiauiCHi on this AFL*PLUS Syst^. 

.~ <3 '. : users: Tothe APL* PLUS System, a user is one individual. Every 
user is recognized by a user name, which is used to log in to the 
system. Every user also has an account number or user identification 
code (UIC), which is used by the APL*PLUS System to identify 
individual users for file-sharing purposes. You can discover your usar 
account numba by entering 1 1 QAI. 

access: A user has access to an APL file when the APL* PLUS 
System permits that person to use it in some way. Typically, you 
haye access to ev«y file Aat you own, jfind can give aece^ te ote 
■ <. '4il9%]i^-^P^'o^^Iy setting the access matrix. 
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ownership: Owning a file or workspace means tluttyoa are the 
person (useraeediiQtttiiiaber) who originally created it cmt most 
leceiuly renamed it 

Comparison ofAPL Workspaces and Files 

There are two ways to make permanent copies of APL data: in a saved 
worlE^xiceorinanAFLfile. APL filc»iad Saved ivoticpKes are 
alike in that: 

• Both reside on a disk. 

• Hwy can be created, used (and pafaq)s modified) over a poiod of 
time, and eiased when they are no longer needed. 

• Both have names and optional library numbers. 

• Both can contain many objects, each of which can be any APL 
value. Stored data can be a scalar, vector, matrix, or higher- 
dimensional array, nested or simple, holding eitha characters or 
numbers. The only limit on the size of a component or variable is 
that it must fit in the available space in the active woikspace and on 
thedi^. 

• They are owned by a particular user,generally the person who created 

There are s(xne important difGermces between a file and a saved 
wcxfc^pace: 

• A woikspace can contain executable prognuns as well as data; a file 
can contain only data. 

• More than one file can be active at the same time. 

■ A file can hold amounts of data that are larger than can fit in one 
workspace (which is limited by the amount of memory installed in 
your computer). The ^ze of a file can range from a few bytes up to 
sevo^ megabytes, or more. 
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' * Hie APL*PLUS System refers to a variable in a workspace by its 
name. The system refers to a component in an APL file by a 
component number that gives the compoient's position within the 
file. Component numlm ate censecittive positive integers ranging 
from the number of the first component to the numb^ of the last 
coinponent 



^ , Pile operations are used to bring the data contained in one component 
' ' . into the active workspace for processing and to save values generated 
in the active workspace as componiHRts of a file. File operations are 
performed through a collection of APL system functions. As system 
functions,, file operations share many of the properties of APL 
ploi^^netioRs: they ate always avallabte fortise In tte 
workspace; they can be incorporated in user-defined functions; and 
many return explicit results that can be used in subsequent operations. 

• The names of the functions used with APL files all start with DF, and 
' ' each name indicates the kind of operation being performed. Examples 
of such functions are QfSEAB (t&t te&i&t^ a eOffiponent fixxn a file) 
- '' ' and UF APPEND (for appending to a file a value from the active 

workspace). The names of the functions for use with native files all 
mn with DAT, and each name indicates fbt ksnd of operation being 
perfianoied. 

Improper use <*E file Operations can lead to file errors. Such errors are 
indicated by error reports. Errors generated by file functions are just 
like errors generated by APL primitive functions in terms of their 
effect on the APL statement in which they occur. Each file Operation 
is described in detail in Section 3-3. 

For an APL file, the directory name or library number and file name 
together are termed the file identification. A file identification used as 
r w,. . . gii igigaiiient to a file function is represented as a vector of characters 
enclosed in single quotes or as any other APL expression whose value 
is a c^ffacter vector. The directory name is represented as a path: a 
^9^(^(£ii%f^^ijnctory maes, sepmteA by the cliaractta- which lead 
to the directory that refers to the file itself. If a library number is used 
instead, it is represented as a positive integer. The directory name or 
. ' ''^Igi^iyigK can be omitted if it is the same as the default directray 
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A file name ecmsists of ton one to eleven q^j^otse htim (A - Z) and 
numeric characters (0-9), and must begin with a letter. If the library 
number is present, it is separated from the file name by one or more 
spaces. Leading aad trailing blanks in the character vector are permitted. 

The rules for file identifications differ somewhat depending upon whether 
directory mode or library mode is in effect If any librari^ are defined 
(using ULIBD OT a startup parameter), the system is said to be in 
library mode, in which file identifications follow the forms used in other 
APL * PLUS Systems. The following are valid file identifications in 
libntry mode: 

' SAMPLE ' (Absoice of library number implies default directory.) 

' 1 1 TOOLS • (file named TOOLS in library 1 1) 

If no numbered libraries are defined, the system is in directcxy mode and 
uses file identifications in the following form: 

' SAMPLE ' (in the conent woiking directory) 

' UOE.USRIDATAQT 

(the file named DATA87 in the sub-directory named 
USR, which in turn is in the directory named JOE) 

Most of the examples in this manual show the use of library mode 
because using it improves portability of code to other APL* PLUS 
Systems on other opiating systems. 

APL file identifications are patterned after workspace identificatianS but 
are logically distinct. A workspace and a file can have the same name. 
They are distinguished at the VMS operating system level by the file 
extension with which they are stored ( . VF for files, . ws for 
workspaces), and they are distinguished in practice by the operation with 
which they are used. 

Native, or VMS, file identifications use the same names both within 
APL and outside the APL environment See your VMS operating 
system manual for the full set of conventions used by your system. 
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To be used, a file mtist first be paired with an integer file tie number. 

All operations on the file will refer to the file by its tie number rather 
than b^ its name. The particular value of the tie number can be any 
flnmb^ acce^ptabte range diat is Mferent ftooi any othw file tie 
numbers already in use. The pairing of a file and a file tie number is 
called a file tie, and a file is said to be tied if such an association has 
been made. 

Descriptions and examples of file operations in (his ch^ter use the two 
files described in Htm foBai*^ {section, D^!^ the fincticMis used in 
dds diqjttf will enable ytm to execmie eadi exaiqde in 



CreaSng and BuOtttng Films 

In the following example, the APL file named PERSONS has four 
components, each of whuh is a vector ot chatacteis. The APL file 
5 also has four c(Miqponents, each of which is a vector of 

numbCTS. 



'2*r *BB€KE1* 20 e 4 

A new APL file is brought into existence with the file function 
OFCREATE, and new components are placed in the file with the 
function UFAPPEND. The following program can be used to build 
the two mes PERSONS md SALES: 

7 SAMPLE1-NAME-PMAT;T;VALUES 

[1] fi CREATE THE FILES 'PERSONS' AND 'SALES': 

[2] 'PERSONS' OFCREATE 5 

[3] 'SALES' OFCREATE 20 

C4] PMAT^ 4 6 p' SMITH JONES KELLEYBECKER' 0 I-l 

[5] fl PROMPT FOR SALES FOR EACH PERSON: 

[6] n THEN STORE THE VALUES IN THE FILES: 

[7] H 

t8] LOOP:''(I>ltpPMAT)/END 0 NAME-^PMATII;! 

C9] 'ENTER VALUES FOR ' .NAME ❖ VALUES*-n 



Fiknaime: 



Component 




PEHSONS 
'SMITH' 

• JONES ' 
• KELLEY ' 



SALES 
5 6 3 1 
2 6 1 
4 6 2 9 1 
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Itm CN*-VALUMS WAPPMrn 20 

Cll] 'VALUES STOSMB IN COMPONENT NUMBER ' .wCN 

El 25 l\APPEND TO FILE * PERSONS' 

[13] T^((NAME^' n/NAME) DFAPPEND 5 

[14] I-I+l 0 -LOOP 

[151 fl 

[16] END: DFUNTJE 20 6 
V 

The UF CREATE operation establishes a new file and prepares it for 
further operations. The syntax (where fileid stands for file 
ideotificaticn and tieno stands for tie number) is 

'fileid' UFCRE ATE tieno 

The file name must be different from that of any existing file in that 
lilnrary, and the tie number must not be in use. When SAMPLE 1 is 
executed, line [ 2 ] creates die file PERSONS and ties it to 5. At 
diis point, the file PERSONS exists in the library, but it is empty 
since it contains no components. Components are added to the file 
PERSONS by the function QF APPEND on line [ 1 1 ] . 

Similady, UNCREATE is used to create a native file. Native files 
follow somewhat different naming conventions and are used with 
negative tie numbers. See DN CREATE in Chapter 3 of the 
APL *PLUS System Rrference Manual for OHHe infonnaticm. 

The function BF APPEND puts a new component, containing an 
APL value from the active workspace, at the end of an APL file. The 
value in the workspace is not altered. The syntax is : 

compno *- value DFAPPEND tieno 

The left argument, which provides the value for the new component, 
can be die name of a variatde; for example: 

name UFAPPEND 5 

The left argument can also be the result of any APL calculation. For 
example: 

(5+2x4 6pl24) UFAPPEND 5 
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The right aignment is the tie number of the file to which data is beiflf 
appended. UF APPEND returns the new componrat number as its 

result. Examples of appending to files SALES and PERSONS 
appear in lines [ 1 1 ] and [ 1 3 ] of 5i4A/fLf 1 . 

-Similarly, □A^i4PP£^/} appends die contrats of an miay, byte for 
byte, at the end of a native file. 

Files created the way PERSONS and SALES were created have no 
maximum size. It is possible to specify a size limit for the file by 
specifying die litnnba- of bytes after die fSs idoitificadon in die left 
argument of DFCSf ^rr. You will receive the error FILf FULL 
if you attempt to put more than that number of bytes of data into the 
file. use of fUe size limits allows yoo to biidi^ 
and |l^i^"nmway"im^gimsfimi fining die entire did^ 

If line [2] of Si4ilfPL£l hadbeen: 

'PERSONS 10000' UFCREATE 5 

the size limit would have been 10,000 bytes. The de&ult value 0 
indicates no size limit 

Untymg Files 

Hie Ainction OFI/yrif has die foltowing syntax: 

UFUNTIE lienos 

It is used to break the pairing of an APL file and its tie number. The 
argument is a vector of zero or more file lie numbers, so UFUNTIE 
can untie several files at once (as in line [16] of SAMPLE!). 
□fj^^rif' has no defect on the values stored in a file. 

Similarly. QNUNTIE is used to break die pairing of a native file and 
ietieQwsber. 
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Tying Files 



An existing file that is not tied can be made available for processing, 
as shown in die next sample fimction. This function inints each Of 
the components of the file named PERSONS along with the sum of 
the numbers in the corresponding components of SALES. The two 
file fimctions introduced in this example ate QFTIE and UFREAD. 



V SAMPLE2:I -.X 

[I] R DISPLAYS TOTAL SALES FOR EACH PERSON 
[2] 'PERSONS' UFTIE 1 

[3] 'SALES' QFTIE 2 
[4] 'NAME SUM' 

[5] • • 0 I-l 

[6] n 

C7] LQOP:^iI>A)/ENB 0 X*-QFREAD 2.1 
rSl (IGiDFREAD l,I).w*/X 
[9] I-I+l « -LOOP 

[10] 

[II] END: 'COMPLETE. • 

7 



The function UFTIE is used to establish an association between a 
file identification and a tie number. This procedure is referred to as 
lying a file. In SAMPLMZ, PER SONS is ded to tie nombar 1 and 
SALES is tied to tie number 2. Hie syntax of UFTIE is 



*fildd' UFTIE tietio 



The function UFTIE has the same effect as OFCREATE, except 
that the file named in the feft ailment must already exist Notice that 
in SAMPLE 1 the file PERSONS was tied to the tie number 5, 
while in SAMPLE2 the file PERSONS was tied to 1. FUe tie 
numbers fi8- use with QFTIE can be any iivieger fi^ I Chr(>Qgh 
2 1 4 7 4 8 1 64 7 . and the niunber for a particular file can be different 
on different occa^ons. 



Similarly, tie numbers for use with UNTIE can be any integer from 
"1 through "2147483648. 
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Rea£ngipim a File 



The function UFSEAD copies the vshie of a ffla onnpwient into ttie 

active workspace. The value can be placed in a variable (as in line 
[6] of SAWPL£2), used in an expression (as in line [?]), or 
dii^l^^^Jliecay at Oe Um^Bal tbi&^cm. of UFREAD (where 
tmnpno stands for componoit nuinber) is: 

res*-UFREAD tieno compno 

The argument of UFREAD is a two-element vector. The first element 
is the file's tie number, and the second element is the compaaetA 
numba. DF^fili} letums the value of the specified file componoit 
as its explicit result - 

Reading from a native file with UNREAD is somewhat mora 
complicated, since the file is not logically divided into components and 
does not internally track the datatype of what has been stored there. 
See UNREAD in Chapter 3 of the APL *PLUS System R^erence 
Manual for miane ioigimsida. 



bumSdnofFik Ties 



The function SAMPLE2 tied the files PERSONS and SALES but 
did not untie them, so those two files remain tied as files 1 and 2. A 
fflifiiHiii^ tied until you untie it OTet^tteAH^s^ ThmaitiBt, 
you must re-(^Ud^^tfie£q}propiiate ties in order to use tte same 
files. 



The status of tied files is not changed 1^ any system commands except 
) OFF. Therefore, loading inlo or dealing the active workspace 
leaves active any ties ietiMevkwslydtenig the This 
makes it possible to load differoit woikspaces to process files without 
having to re-establish the ties. 

UsOng FOes in a FmUbnay 

■i ' • • 

The names of the files in a particular libiaiy cff iSrectory areobtamed 
with the function UFLIB. The syntax (where fife stands for library 
number or directory name) is : 
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result *■ OFLIBUb 



result is a character matrix. Each row holds the identification of a file 
in the designated library. If, for example, the program SAMPLE 1 
had been created by a user in library LJOE .USRl, thai the 
expressions: 

ULIBD '101 IJOE.USRl' 
UFLJB 101 

produce: 

101 DATAl 
101 SALESSl 

M the AJPL ffles in a library or directory appeat in the result of 
UFLIB, even those that the user account number requesting the 
display is not authorized to use. 

UFLIB 1 0 lists the APL files in the current default library 
(wcHking directory). The system conunand )FLIB yields the same 
infomiatiion as UFLIB. 

Similarly, DLIS and )LIB return a list of all files (native, APL, 
and even workspaces) in a format consistent with native file names. 

Erasing FUes 

When an APL file is no long» needed, it can be oased using the 
function UFERASE: 

fileid UFERASE tiem 

The file name is then deletssd torn die library. All of its components 

are desU'oycd, and the spaCe they occupied is made available for use by 
other files. Since the file no longer exists, the file tie is also broken. 

A file must be tied before it can be erased, and both the file name and 
the tie number must be given. Similarly, DNERASE can be used to 
erase native files. 
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Cop^g Values from One APL File to AnoUier 

The following function is an example of changing the arrangement of 
. -ffled information. The components of PERSONS and SALES sxa to 
. - be merged into a new file RECORDS. Each odd-numbered 

component will come from SALES. The two original files are erased 
after the merge is complete. Recall thai PERSONS and SALES are 
still tied following execution of SAM PLE2. 



V SAMPLE 3 • T 

111 (\MERGE FILES TIED TO 1 AND 2 INTO 'RECORDS' 

L21 'RECORDS' OFCREATE 3 « I-*-! 

[3] n 

[4] LOOP:-'(.I>i)/END 

[5] T*-(nFREAD 1.1) QFAPPEND 3 d FROH 'PERSONS' 

[6] T-^IOFREAD 2,1) WPAfPEHIi 3 A FttM 'SALES' 

C73 1-1*1 0 -^LOOP 

[9] END-.nFUNTIE 3 

[10] 'PERSONS' QFERASE 1 0 'SALES' QFERASE 2 

V 

'NOte'ttaiHi^en die files have been met^, die new file RECORDS 

(tied to 3) is untied. It is not necessary to untie the files tied to 1 and 
2 because erasing the files unties them automatically. 

Senvfe Handling of a Niigw Ftte 

'1 ■ . 

This example shows how a naliire file can be ac6(^ed ffiKi imatipalated 

from within APL. Suppose that a VMS file NAMES contains a Ust of 
names to be sorted into alphabetic order. The file is structured like a 
typical VMS Stream_LF file: it is a linear sequence of characters, and 
the VMS newline character (OrCLF) separates the names. (Note that, 
in native VMS conventions, nrCLF and not DTC/ZL is used as the 
ikif Qae;£|bpK!ttt^ The lines in the file aie of varying lengths. 

The system function GNTIE ties ("opens") the native file: 

'NAMES' UNTIE "5 

and the fiinctioa UN SI IE teipoos the total number of bytes in the 

file: 



Copyright © 1987 STSC, Inc. 



3-13 



5129 

Using the system function UNREAD, it is possible to read a sequence 
of data from the file. For relatively small files such as this, the 
simplest method may be to read the entire Hie into the APL workspace 
at once. The following comnuuid reads the entire file and stores it in 
the variable F: 

F->-nNREAD -5 82 . ( UNSIZE "5 ) , G 

The character vector can then be arranged into ascending order by 
convoting it into a nested array (a vector of names) and arranging 
those names into the desired order. Once the names are rearranged, the 
list can be written back to file. In this case, since the length of the 
file does not change, you can replace the file with the new values. If 
F5 is a chaiacter vector containing the sorted form of the file, then the 
following statement will write it to file: 

FS QNREPLACE "10 

The statement means "take the contents of FS and write them over the 
present contents of the file, starting at byte 0 (the first byte)." 

Putting the ingredients together, the following function sorts a native 

file into alphabetic order by lines: 

V SORTFILE FNAME -.LINES iGRADEVEC 

CI] FNJmE nNTIE -% ft fiE THE FILE 

E23 LINES *- m&EA^ "l S2.CEWSIZ£ "n.O A AND READ IT 

[31 LINES*-TiTCLF .LINES A LEADING DELIMITER ON FIRST LINE 

[4] LINES-iy (LINES=nTCLF)cLINES rCONVERT TO NESTED ARRAY 

[5] GRADEVEC-DAV^Ur /^,/p--LINES)t"LINES o GRADE 

[6] LINES'^LINESLGRADEVECl fi REARRANGE INTO SORTED ORDER 

[7] LINES-^-ll^ , /LINES ."QTCLF fl CONVERT TO SIMPLE AGAIN 

C8] LINES UNREPLACE "1 0 fl WRITE BACK TO FILE 

[9] UNUNTIE -1 



Comparisons with Corresponding Native File Operations 

The correspondence between APL file operations and native file 
operations is not always exact. In particular, note that; 
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NiUive fiSes^ahvapQsed with diiectoiy names. Lilxary numbers 
do not iq}ply to native files. 

■ H^advedeaunbeESffieitpifedfiVKitivefUte^ 
positive tie numbos used with AEL files. 

• BNM^AD needs a mcffie cofflfAex right aigumait since the file is not 
organized into componoits. 

retaining no infarmation about the atr^ such as sliq)e, datatype, or 

origin. 

• There is no native file feature that is a close analogy for UFLIB 
and )FLIB. The results of DL 15 and ) L 15 include all APL 
files and all AFL wodcspaces too, since these are sttHed (HI £sk as 

•- '"~-""':tgtt^effiles. 

A more detailed ccMiqKBison of native and AFL files can be found in 
Secti(»3-7. 

3-2 Mom Personal File Management Facilities 



This section covers the remaining file functions used with both shared 
and nonshared files. The examples in this section assume prior 
cxes&m m& ttM^md m not hiteiided t» ^toect keyboard 
execution as were die rauunples in Section 3-1. 



Two system fimctions, QFNAMES and DFNUMS, Kgm the names 
and numbers itfttiecunaitAFL file ties. OFNAMSStmrasa 
character matrix in which each row is the library number and name of a 
currently tied APL file. UFNUMS returns a vector of their current tie 
nuntes, in an ofder c(»ie^(»ding to die names returned by 
UFNAMES. 



lU0^0g3f^mftte Ties 




lis inSnrmation is created by: 
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DFNAMES . ' 110' UFMT DFNUMS 
SAMPLE 1 
PERSONS 2 



The simplest way to untie all tied APL files is to execute the 
statement QFUNTIE UFNUMS, since the vector relumed by 
UFNUMS is exacfly what UFUNTIE needs to untie all files. 

Similarly, the functions UNNAMES and DNNUMS report on the 
status of native file ties. Giv^ the ne^tive tie numbers fca native 
files, ifae cQirespmiding forniula for a tabular di^day is: 

QNNAIfES,* 1 11' UFMT QNNUMS 
Replacing e File Component 

A file component can be replaced by a new APL value udng the 
function UFREPLACE. The syntax is: 

vabie DFREPLACE tieno a>mpm 

F(^ e3«Qffiiple, to li^Iace die second component of the file tied to 1 
with the character vector ' REPLACED ' , the following statement 

could be used: 

* REPLACED' QFREPLACE 1 2 

The new valiie am be any AH. vafaie that fits in the active wotlospace. 
If the new valtie is laisa: dian the previous value, additional file 
storage is autoRiatiCidly provided. 

A common use of UFREPLACE is to update a component by 
modifying its value. In this example, the value of the variable debit is 
cat^i^ed to die existing value component 3 of the file tied to 7 : 

{(.UFREAD 1 3). DEBIT) UFREPLACE 7 3 

Note that the new value is larger than the value it is replacing. A 
replacement component need not occupy the same amount of space as 
theoldvahie. 
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TheccnespoiKling ti^^ 

to components; in pUlce of a component number you supply the first 
byte in the file to be iq>]aced by the given value. That value will 
iiepbi@6etaedy the amoimf (tf the file needed to slc^ 
what was there before. The programmer must evaluate positioning and 
space requirements. If more data is to be stored than the remaining 
space in die file ^ aceoramodate, UWMPLACM ^1 lengfim the 
file to make room for the rest of the data. For additional details, see 
UNRE PLACE in Chapter 3 of the APL *PLUS System Reference 
Manued. 

Dropping Components from Either End of a File 

The function UFDROP ranoves compcxients fiom dthn aid of a file. 

The syntax is: 

OFDROP tieno n 

The argument to UFDROP isa two-elemoit vector. Hie first element 

is the tie number of the appropriate file. The second element is an 
integer specifying both the number of components to be dropped, and 
filKn which end of the file to drop them (shown by the sign of n). If n 
is positive, the specified number of components are removed from the 
front of the file; if n is negative, the components are removed from the 
end of the file; if n is zero, no components are removed. The 
component numbos of the remaining components are not changed. 
For exainpl^ if ttie ffle IkA to 99 has ten components numbered 1 
'i l^iiBlbilOf tl>^ e^KCUting: 

UFDROP 99 4 

the file will have six components remaining, numbered 5, 6, 7, 8, 
9, and 10. A fivtfier execution of: 

UFDROP 99 "2 

will leave compon«its 5, 6, 7, and 8. 

Components omnot be Stopped from the interior of a file. Other 

techniques can be used to signify that an interior component holds no 
information and should be bypassed in later processing. Perhaps the 
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simplest way is to replace the component with an empty vector ( ' ' ). 

There is no native file operation that corresponds to UFDROP, since 
native files are not organized into ccmpoaeitas. 

Determining the Size of a File 

Ite foncticm UFSIZE, with syntax : 

result *- DFSIZE tieno 

returns a four-element vector. The first two elements are the 
componrat limits of the file: the number of the first component, and 
a manlier diat is l higher than the number of the last component. 
The component limits of a newly created file are 1 1 . 

A count of the nomber of components in the file is givoi the 
following exjn^sion where tn is the tie number: 

l-/2tDFSIZFrn 

The diM and fourth elements of the result of UFSIZE are the 
amount of file storage currently occupied by the file, and the file 
snaage limit, in bytes. If the fourth element is zero, the file has no 
imposed size limit other than available space on Ae disk. 

The corresponding native file opoation, QNSJZE, returns a single 
number representing the number of bytes in use. Since native files 
have neither components nor automatic checking for maximum size, 
tha« can be no meamngful equivalents for the odier numbers in 
UFSIZE. 

Suppose the result ot UFSIZE for the file tied to 1 0 is as follows: 

UFSIZE 10 
1 126 259584 265000 

The result of UFSIZE indicates that the components in the file are 
numbered 1 through 125, inclusive, and that the size limit for the 
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now occiq)ied, 

FoBowing are examples of how to impianent two common file 

organizations -- "first-in, first-out" (FIFO) and "last-in, first-out" 
(LEFO) - using UFDROP and UFSIZE. The examples use a file 
liedfo SO. 

FIFO organization: 

DatacoIlecttOT: data UF APPEND 50 

SIZE *■ DFSIZE 50 

■ ■ Subsequent INFO *■ UFREAD 50, SIZE 1 11 
processing: 
' " (fHDCess info) 

M ■ . 

UFDROP 50 1 
LIFO organization: 

Datacollection: data UF APPEND 50 

SIZE UFSIZE 50 

Subsequent IVFO *■ UFREAL 50,SIZ£C23-1 
6 imacessing: 

■ OJrocess info) 

QFDROP 50 -1 

With each of these schemes, the data collection and processing phases 
can be executed when it is convenient to do so. You can collect data 
whenever infi)rmat!on is available and pxxxss dlsria whm the fite 
becomes large and unwieldy or at some fixed into^al; oice a day or 
once a week:, for example. 

After a component is processed, the storage it occupies is generally 
released by executing UFDROP. In some cases, nFDUP is needed to 
reclaim all dsss^esdssma^si ^ Chaptsr 3 (tf tfie APL *PLUS System 
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Reference Manuat fbr iftoe information. Consequently, data can be 
collected and processed almost indefmitely and never requiFe mcne than 
a relatively small amount of storage space. 

As an example of using UFDROP with a file whose components are 
released in an arbitrary sequence, the following function produces an 
invoice from information in a file named CDATA. After the invoice 
is produced, the appropriate component of CDATA is dropped (if it is 
the first component) or replaced with an empty component (if it is not 
the first component). Each time it iS ased, &te function checks to see 
if the last component of data is an empty vector; if it is, that 
component is dropped. This technique tends to minimize the file size. 

V SAMPLE A iLIM-.N 

[I] 'CDATA' DFTIE 5 

[2] 'ENTER RECORD NUMBER' 0 Vo-Q 
[3] H TEST COMPONENT NUMBER: 

[4] LIM^ZtDFSIZE E>0^( (N<LIM\.l'\)vN>LIMLZl)/ERROS 

[5] H READ RECORD AND PRODUCE INVOICE: 

LSI RECORD^OFREAD S,N 0 ^(.Q^pRECORO) /ERROR 

t7] PRINTINYOICE RECORD 

C83 • • aWMMFJ-ACi S,lf 

m H mtm any bmpty mMPONEurs 

tlOl n FROM FRONT OF FILE 

[II] LIM*-2tnFSIZE 5 

[12] L00P:-(.LIMlll=LIML21 )/ENDnTEST FOR EMPTY FILE 

[13] fi TEST FOR EMPTY COMPONENT 

IIA'\ -'(Oitp.OFREAD 5 ,LIM121 -1) /END 

[15] ft DROP EMPTY COMPONENT 

[16] UFDROP 5-10 LIML21-LIM121-1 0 -LOOP 

[17] ft 

[18] ERROR: 'THIS RECORD NUMBER NOT IN FILE' 
[19] ENBiUFUNTIE 5 
7 

In line [ 4 ] of SAM PLEA, a branch is taken to ffloror if W is not 
within the range of the lowest and highest component numbers. 
Otherwise, line [ 6 ] reads the component, branching to error if the 
component is empty. Line [7] calls the function PiflWriWyOICf 
(not shown) which actually produces an invoice based on the record. 
IMm till ta>ilgh 1 1 4 ] drop empty components, if any, from the 
06. Ndte the checking for an empty file in line [12]. 
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The above dtectission presents a limited reisesentation of possible flle 

organization techniques. There are more static forms of database file 
organization that subdivide the data and keep directories. Also, there is 
a wktespeead CM»r@tttim of leserving ifae fim 
description of the file. 



The function UF RENAME is used to change an APL file name. The 
isyittfo is 



can be used to change the name (rf a file in a library: 

'REPORTS' UFTIE 100 
. . 'OLD^ PORTS' UF RENAME 100 
UFtmriE 100 

Note that UF RENAME does not create a second copy of a file. After 
the execution of the pFevi(»s otample, REPORTS "vtmSA imt 
dsi^jfieared fiom the libiaiy. 

In addition to ^an^g Ae nante^ UfRMHAIlM fdso mts fhe 
ownership of the file to match the vsa acccMint numbs' md^ whidi 
the opoation was performed. 



The system function UNRENAME is used for renaming native files 
and for moving a native file into a different directory. 



The function OFMSIZE can im|iQ$e a ^ limit on an AFL file 

beyond which the file is not permitted to grow. For example, if you 
did not want a Umit when you firstcieated the file but have changed 
your mhid, use HFRESIZE. 

Sometimes a file needs to hold more data than iU current size limit 
^ llU@w. Wm t fite d^ liot have enou^ room for the value to 
be stt»ed in it, a FILE FULL error occurs: 



jRmtmingaFUe 



'fileid' UF RENAME tieno 





' OLDREPORTS' DFTIE 12 
REPORT UFAPPEND 12 
FILE FULL 

REPORT QF APPEND 12 

A 

The fourth element of the result of QFSIZE shows that the size 
limit for the file OLDREPORTS is 100.000: 

QFSIZE 12 
1 34 99512 100000 



The function UF RE SIZE can be used to increase the Hie size limit 
so that tfaoe vnU be oiough room tt) perform the desired i^n^ 
opoatkn: 

2 0000 0 UFRESIZE 12 
QFSIZE 12 
1 34 99512 200000 

REPORT DF APPEND 12 

34 



The syntax of QF RE SIZE is: 



newsize UFRESIZE tieno 



whae newsite is die new file size limit. It is also possible to deorease 
the size limit of a file, provided you do not specify less storage than is 
idteady being used by the data in the file. In addition, you can always 

0 QFRESIZE 12 
RESIZE 12 
1 34 99512 0 



to remove the size limit le^riction completely. 



Thete bo sfsntm ftmction ftff native fil^ ftat opoe^onds to 
UFRESIZE, since native files do not have size limits. 
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Copying a FUe 



The function QFDUP is used to make a duplicate copy of the contents 
of an APL file in anodier APL file. The aspy need not be in fte same 

library as the file being copied, and the name need not be the same 
(although it can be if the library number is different). 

• 5440 FIGHT' UFTIE 48 
' 1844 OREGON' QFDUP 48 
QFUNTIE 48 

The dttmoship of the original file iis unchanged by OFDUP, but the 
to^^aoiikim iiumb» that used is Ae owner of the 

T%eie is no need to untie the new copy (' 1844 OREGON ' ) since 
it wasliever tied. If you were to tie the new copy and compare its size 
(using DFSIZE) to the size of the original file, you might find that 
the new file was smaller, since UFDUP elin^n^ 8^ space 
06iyfi^ (see "Counting a Ffle", below). 

> '- '-- There is no system function for duplicating native files, but you can 

use the VMS command "copy", either from VMS or with ) CWD, or 
under program control with □ CO. This method can also be used to 
' copy any file, including APL files aiidsffysedw{»d^^ 

To move a iSle fim onl Qbtary to maibis, use DF REMAKE finr APL 
^« and nyOi/ilJIff for native files. 

Compacting a File 

The function QFDUP can also be used to compact the contents of an 
APL file. First, make a new ecmpet^mfj v^ag OFBUP. If you want 
the compacted file to have the same name as befor, 'first use QFDUP to 
create a new file with a different name. Then erase flie original, rename 
the new compact copy to the original file name, and tie the compacted file 
to the same tie numba that the original file was using. 

'5440 FIGHT' UFTIE 1844 
'TEMP' QFDUP 184 4 
•5440 FIGHT' QFERASE 1844 
'TEMP' UFTIE 1844 
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'5440 FIGHT' UFRENAME 1844 
QFUNTIE 1844 



The user account number that used UFBUP to compact the file 
becomes the own» of the file. 

Since storage space is limited, it may be necessary periodically to 
reclaim file space containing abandoned data. The data may have been 
abandoned by the use of UFDROP or UFREPLACE with a different 
amount of data. The APL *PLUS System does not automatically 
release for reuse all the space occupied by abandoned data within APL 
files. It is liwnseifs reqiaKitnHty to reclidta storage space as needed 
by usiBg DFDt/?. 

There is no systnn fiinctioa for compacting native files, since the 
system does no traddng of theff amtmts. 

3-3 Foe Sharing — Concept and Functions 

The shared use of a file falls into one of two general categories. The 

first, discussed in Sections 3-1 and 3-2, is that in which only one 
person at a time may use a file (that is, have it tied). The second 
category dFsluiring, discussed in Siections 3-3 and 3-4, involves the 
concurrent use of a file by two or more people; rather like the use of 
several telephone receivers on one telephone nimiber, which may 
nqosesoBiepioidccdiBnQi^gKatse^ Section 
3-4, describes some mechanims foe the detailed control of concurrent 
file sharing. 

The FUe Access Matrix 

Associated with every APL file is an access matrix that records which 
user account numbers are authorized to use the file and which file 
operations each can perform. 

Every access matrix is an integer-valued matrix with three columns and 
any number of rows: 

• Column 1 is the user numba to which access is granted. 

• Column 2 indicates which operations a user is authorized to perform. 

• Column 3 is a fossnumbn to the file. 
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The following table shows typical entries in an access matrix. The 
details of columns 2 and 3 are of interest only when exercising detailed 
'Ci^c^m^Becessrthey are discussed in Section 3-4. 

Encoding of 

*^W&eiti«sr Operatioiis PassBomber Desta'iption 

^- 12 3^45 ~1 0 Acce^ granted to uso' 

12345. 

234 56 9 5 Access granted to user 

' 23456. 
0 10 Access granted to all 

other users. 

A user account number in column 1 can be that of any user, or it can 
be zero. Zero represents all user account numbers, except the file 
owner's, Aat do not qipeardsewhece in column 1 of die access 
matrix. 

When UFTIE or UFSTIE (a variant of UFTIE described later in 
this chapter) is executed, the access matrix for the file being tied is 
searched for a row containing the uso- account numbo-. If a row is 
found whose first element matches the user account number or failing 
diati a row is found whose first element is zero, then the authorized 
'^fmm^aeeimmttkmtimti^ Any 
attempt to use a file opraation that is not authorized will result in a 
file access error. 

The owner of a file has complete access to the file if column 1 of the 
access matrix does not contain his user account number. No one else 
has any access at all unless there is a match with his user account 
number or a zero in column 1 . If a person with no access attempts to 
'fie die file, the system will produce a file access error. 

Functions lite DFNAMES and QFNUMS are not restricted by access 
matrix settings and never produce a file access error because they are 
not performed on a particular file. Also, there are no limitations on 
UFSIZE or QFSTIE; these are permitted if any other file operation 
isnuAeiiEed. 



The fuQeti0n8 aFRBAC mi DFSTAC (dwcribed in Section 3-4) can 
be used to manipulate die access matrix. 

Fik Component Ittformation 

Along with the value stored in a component by appending or 
t^laelitg, four other pieces of informaticHi are carried with each 
con^nentof afile. They are: 

• die w(»dcspace storage needed to hold the componoit's value 

• the user account number of the person who last replaced or appended 
thecompcxient 

• the time that the ccnnponent was last replaced or appraded in a 
packed-timestamp fonn 

• the component timestamp in a seven-element unpacked form (year, 
moBtb. date, hour, minute, second, millisecond). 

The function UFRUCI reads this compcment infonnation; its syntax 
is: 

result *- UFRDCI Heno cofnpno 

The result ofQFRDCI isa ten-element numeric vector holding the 
infc»tnation described above. The packed timestamp in die diird 
element of the result is given in microseconds since 00:00, 1 January 
1900; under program control, it is convenient for comparing the 
dmestamps of two components. 

The function QFRDCI is particularly useful in data collection or 
audit trail i^ticadons, where sevaal pa^s may have access to 
append to a file. As each person appends, the component is 
automaticaUy tagged with the time and the person's user account 
number. Imc, when a aset with UFREAD mi UFRDCI 
authoriza&m processes die file, the source of each component is 
clearly indicaied. 
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Concurreat Sharing of Files 



The previous discussion covered the first category of shared file use, in 
which only one person at a time is using a file. The use of DFTIE 
to establish a file tie assures this kind of exclusive file use, since 
QFTIE will produce a file tied error if any other us^ tri^ to tie the 
file. Thus, □ FT IE provides you with exdimve use of a file until 
youmitieit. 

The second category of file use covers situations in which several users 
may have the same file tied concurrently. Two file functions are 
needed for concurrent file use: QFSTTE mi& OFH&LD. 

The function UFSTIE, with syntax : 



est^lishes a tie to a fite, (smetly as QPTIM does. However, this 
"shared tie" also permits others to share-tie the same file. UFSTIE 
can be used to share-tie a file if the file's access maoix allows the user 
any form of access whatever, provided no oie has the file exclusively 
tied using DFTIE. 

■ I . .When several persons are using a file concurrently, their file operatioi^ 
proceed asynchronously, and it is quite likely that one person's 
processing may be interleaved with another's. For example, suppose 
that users P and Q have the file tied to 7 7 and are trying to add 1 to 
the value of component 5; they use the following statement: 



'fiUid' nPSTIEtiene 




n*UFREAD 77 5) UFREPLACE 77 5 




lih^bi^tii are j^ikM, cimpmoit 5 sMhlbe ii»»iei$ed by 2. But 
suppose the parts of Uie statement are executed in diis sequence: 



,P,: .-- 



Q 



QFREAD 11 



5 



mMM^ 77 5 



(addl) 

UFREPIAQM 



77 i 



(add 1) 

UFREPLACE 11 5 
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The value of component 5 is increased by only 1, since Fs program 
destroyed the value stored by Q. 

What is needed here is an interlock to prevent P's program from 
executing any pan of the foregoing APL statement while Q's program 
^ ^(ei»i^ it (and viee vrasa). The function UPHOLD {wovides this 
interlock. Its syntax is: 

UFUOLD tienos 

The effect of executing UPHOLD is to place an interlock on each file 
whose tie number is included in the right argument The concept of 
this interlock is subtle; in effect, using UPHOLD means "wait until 
no one else has these files held, then hold them for me." 

UPHOLD executed by P, for example, has three effects: 

• Any interlocks in effect from a previous UPHOLD executed 1^ P 
are released (even if they held the same Bki). 

• P is placed in a queue behind every other user who has already 
executed UPHOLD for any of the files specified by P. Fs program 
is delayed untfl no one else is holding any of these fDes. 

• Interlocks are set simultaneously on all the designated files, and P's 
fitidgiain dten tesimies execution. 

Many people misunderstand file holds when they are first learning 
about APL files. They assume that "holding a file" means they are 

preventing others from using the file while they have it held. The 
only effect of a file hold is to delay the execution of UPHOLD in 
odia'tism' programs. In odier words, no two ^ers can ilve the same 
file held at the same time. File holds do not block other file 
operations such as UPRPAD or UPRPPLACE. 

UPHOLD does not prevent other users from using a file while you 
have it held. Bui UPHOLD does provide a means for two or more 
users to coopetatB and avoid conflict in file use. For example, suppose 
the program executed by P and Q in the previous ^cample is changed 
to: 
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UPHOLD 77 

(l*OJFJ£7l2) 77 5) GFRE PLACE 77 5 . 
OFHOLD lO 

Then the first user to execute UPHOLD 11 is able to proceed 
without delay, wh8e tm ^^^ m^t jpsipatti is delipd wtil die first 
user's program KtecQtes QFHOLp lO. The sequence would locdc 



UPHOLD 11 

I . (delay) . 



(proceed) 

UFREAD 77 5 

(add!) 

UPREPLACE 11 5 
UPHOLD lO 

(proceecO 



UPHOLD 77 . 
^xtceed) 

DfSfvli) 77 5 
(addl) 

UFREPLACE 77 5 

UPHOLD vO 

(proceed) 



When Q executes UPHOLD 11, he. establishes a hold on the file 
that prevents P from establishing a hold. In Fs program, UPHOLD 
simply waits untQ its turn comes to beM ^ tie, whicli happens when 
Q executes UPHOLD i 0. P is then#le to hold the file and 
execution proceeds. This makes it pos^ble for cooperating users to 
avoid conflict 



lip^ver, if Q does not use UPHOLD properly, then there is nothing 
1p' dia do alone to prev^t conflict Suiqx^e P is using UPHOLD: 



UPHOLD 11 

n + UPREAD 
UPHOLD lO 

And Q is not using UPHOLD: 



77 5) UFRE PLACE 77 5 



i ' MMIFREAD 77 5) UFREPLACE 77 5 



The interaction could then be just as if P woe not using UPHOLD at 
alL- 



P 



Q 



UPHOLD 11 
Qxoceed) 
DFSfi4i) 77 

(addl) 



5 



UWtEk-D 77 5 

(addl) 

UPREFLACE 11 b 



UFREPLACE 77 5 
UPHOLD lO 

Only when all parties cooperate can conflicts be avoided. For this 
reason, it is often wise to require the use of a specific function to 
access a file - one liiat obeys the desired protocol. File pasatumbers 
(discussed in Section 3-4) iRovide a means of oifoicing the use (tf a 
given protocol. 

Here are some situaticxis that do or do not lequiie file holds in order to 
work properly: 

• Several users are concurrently appending to a file but make no other 
use of the file. File holds are not needed since UP APPEND will 
keep track of componoits added to the fUe by nulnb^. Although it 
is not possible to predict in what order the various values will 
appear in the file, any request for a file operation (in this case 
UFAPPEND) always waits until a pEe^^oiB tqiaration on the same 
fileisctHnplete. ThLsstatemoit is being used: 

mycomp *■ value QF APPEND tn 

The result of UPAPPEND lets each person know which component 
contains his value. 

• Several users are reading and replacing components of a file, and it is 
known that no two users ever referoicefte same component. Wot 
example, Fs program refers only to component 1, Q's program only 
to component 2, and so on. No hold is needed, since no conflict can 
occur on the concunmt use of a single component 

• An application involves die use of three files in which 
like-numbered componoits contain related d^. One program is 
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f " ' - ^ ••' '^-^[Jdsifffiftg^ files wWte tise othff programs are reafing the files 

concurrently. To ensure that no program reading from the files will 
encounter a mixture of old and new data, the updating program has 



UPHOLD 21 22 2 (process and replace component n 
(£ mih of die three Eiss) 

DFHOLD 10 

and the file-ieadin^piograins ^ $m 'SgBie^&^ ccmmmmity have 



UPHOLD 21 22 23 
yl - UP RE AD 21.N 
" B *- nPREAD 22, N 
C DFREAD 23. N 
UFHOLD lO 

This is a situation where file holds are needed in a program that is 
. UseMmkmo^ifymg the cont^ts of any files. 

As these examples show, the need for flle holds depends upon the 
interrelation of program and file structure. The design of any 
applicadon involving concurrent use of files requires careful analysis 
for possible "races" bdtKfie«ii»ograms. ¥oa caniesolvera^ ccmflicts 
wMta aipopnaie use of OFHOLD, 



Dumtion ofFik Holds 




All interlocks are released when the user who set them executes 

}, agns dS, at eaters immediate ^eeation mode. 

: on a single file can be released by untying it or retying 
it K(^lhai UPHOLD 1 0 releases all interlocks. 

The immediate execution case is particularly important to remember. 
If you type the following three statements as three different immediate 
«K$»saiiffli inputis: 



UPHOLD 1 
PROCESS 1 
UPHOLD lO 



like the following will work correctly, since there is no immediate 
execution input between QFHOLD and process: 

UPHOLD 1 ❖ PROCESS 1 0 UPHOLD lO 



3-4 Detailed Control of File Sharing 

This section covers some mechanisms for limiting file access to 
particular parts of a file or to specific sequences of file operations, 
primarily for designers of laige-sctde, shared-file tftpiieadstis. Mm 

readers will find the facilities described in Section 3-3 adequate for their 
needs. Section 3-5 contains a more detailed discussion of the access 
matrix. 

For simplicity in the examples that follow, the syntax of APL file 
operations does not inclu^ the optional passnumber argument. 

Setting the Access Matrix 

The value of a file's access matrix is set using the function QFSTAC. 
The syntax is : 

nuurix UFSTAC tieno 

The left argument is an integer-valued, three-column matrix. A three- 
element integer vectca: is reshaped to become a one-row matrix. It 
replaces the previous value of Ae access matrix. Inifially, when a file 
is created, its access matrix has no rows: its shape is 0 3 . The file 
owner has complete access since his user account number does not 
appear in column 1 and no one else has any acc^ for die stttne r^@on. 

Reading the Access Matrix 

The access matrix is read into the active woricspace using the functicm 
UFRDAC. The syntax is: 

result *■ UPRDAC tieno 
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The smSltxs access matrix for the file tied to the nnmber in the 
right argiunraL The second element in a row of the access matrix is 
the sum itf access code values for the particular file operations that are 
allowed W the user account number in the fiist positicw of the row. 
The access code values are : 



:v.-ii J'. sjf h'' 1; n; U.K. f^i ' 1 ,.^:rtP9de Operation 

1 UFREAD 

2 UFTIE 
4 UFERASE 



: : ' / ---'rj:. . ~ 1 UFREAD 

liiai ilitv* i-:m. n't ">.-.j.-:i'.i r.. . »|- Ji/v.-ji,', i : ,•: ....i ; . 2 UFTIE 



32 DFDffOP 



"^'^i' ■ "can": i*: 



64 (Not used.) 

128 nFnmAKE 

25 6 (Nottaed^ 

512 □f«J5Cr 

1024 UFRESIZE 

2048 UFHOLD 

4096 DFPMC 

8192 DfSrAC 

16384 QFMF 

3 276 8 (Not used.) 

6553 6 (Not used, represaits OF STAT US on other 
AM.*PLUS Sys^s.) 

The sum of all possible access codes can be used to authorize all 

ileopaati<»s. A ~1 canalsobeusedto^cantfullacce^. 



A value of 9 indicates authorization to execute the functions 
□fi?fi4Z) and Of j4PP£'W0 on the file. Any non-zero value permits 
use of Of 5 JZf and Of 51 J£; obviously, not all combinations of 
values make sense. 

Using Passnumbers 

The third element in a row of the access matrix, the passnumber, is 
usually zero. Nonzero passnumbers are used only to exercise detailed 
control over file access. If die diiid dement coniJdns a pasmmiber 

other than zero, the user whose user account number is on diatrow 
must provide a matching passnumber to operate on a file. 
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OaiittH^ a pasaiamber fitMn an aigmnait (i& ia all uses of file 

functions in Sections 3-2 through 3-4) is equivalent to providing an 
explicit passnumber of zero. A mismatching passnumber causes a 
FILE ACCESS ERROR. 

Passniunbers are intended for use within locked APL functions that the 
application programmer gives to users in place of the standard file 
functions. Suppose each component of the personnel file 2 3 4 5 
PERS is a vector holding an employee's telephone extension and 
room number followed by salary information. The user with user 
account number 9 8 7 6 is to be allowed to retrieve the telq)hone and 
room number but not the salary information. 

For example, the programmer chooses a passnumber, 10349, and 
defmes these locked functions: 

PTIE 

in '2345 PERS' UFSTIE 25 10349 



R*-PREAD N 
111 R*-2fnFREAD 25.^,10349 

B$Btt,hese@ttieaeiC^o»ittte for 2345 PfJZS to authorue access 
l9usa'9876. The row of the access matrix will be 

9876 1 10349 

Finally, the programmer gives the locked functions to user 9 8 76, 
but does not tell him what the passnumber is. Now 9 8 76 has 
permission to tie and read from the file, but only if he gives the 
passnumber with each UFSTIE or Q PRE AD. Since he does not 
know the passnumber, he can access file 2 3 4 5 PERS only through 
the functions PTIE and PRE AD. 

Using this general technique, it is possible to impose complex 
restrictions on file authorization; in fact, you can impose any sort of 
restriction that can be stated as an APL function. Since different 
passnumbers can be imposed on different user account numbers, it is 
easy to provide multiple levels of access authorizaticMi to confidential 
data. The {sevioiisesanqitle showed access testrici^ 
within a c(Hnp(»ienL Examples of oAer fonns of cmtrol are : 



Copyright © 1987 STSC, lac. 



3-34 



vi: • - ; • acc^ oidytoeven-numboedcoHipon^ts: 

[1] DERROR (.Q^ZIN)/ 'EVEN NUMBERED CNS ONLY' 
1- - c'..\--'i"[ ^,a^.: .^nM ■-. . , ,12]. R*-QFREAD 25. N. 32049 

• access only during the aftmtoon: 

!.■.(.. j.J.i5,itrj n [1] DffifiOfi (-DTS [4 ]el2 13 14 15 16 n)/'PM ONLY' 

..jrx , yfi ii 12] R*-nFREAD 26, N. 320 A9 

automaticlogging of information requests: 

, ^, , ,^ , , , > , UFAPPBND 99 2888 A LOG TO FILE 99 

-vi- = nj...v .•..r. . .v.;. . ; ,i. ^^^y IMIFSBAB 25. (W) . 32049 

.i%-.^«}s;- .vr, Lateruseof □fJ2£i4DandOf«i}CIonflieffletiedto 99 will 

' . : ^ . - l^ve die vtdue of ff,ttetimestamp, and the isquestcK'sim account 

number. 

" ^ - - • i , jKxxss only after >nUdatin^ 

Cl] -(.l^ppV)/ERR 0 -( (20»'p/)v0v. >V)/£i?* 
Ml R^Y QFAPPEND A6 14149 



acces only aosr vien^jmg vm mmm W f^t>^ and answers 
^ protect a mcmi^ittfay anateeoded compu^ from passosby). 

access only to sumnuffy data (for instance, salary average but no 
individual salaries). 



3-5 The Access Matrix 



!f-,i!r,-' ..li ; ■I'M.-. 



AU files have access matrices Ihst e^idale il^hich users can use 
them and which operations each user can perform on them. The rules 
applicable to an access matrix are as follows: 

• Every access matrix is an integer matrix with three columns and any 
number of rows. Each row in the access matrix represents the 
authorization granted for a single tuer (»: class of users. The first 

. column of the matrix contains a user number; the second column 
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OHitgtes m iei@iBig of ^ etstmpoadme ia^fya0mA opiatioiB, and 
the thiid coiumn contains a passnumbor. 

• Tbe user nombers in column 1 can be those of any usees. A zoo 
value in column 1 refers to all users other than the owns or those 
explicitly specified elsewhere in column 1. 

The owner has full implicit access only if his user number does not 
explicitly appear in column 1 of the access matrix. If the owner 
does iqypear expUdtly in the access matrix, then he is treated just 
Uke any otho: user. 

• Ilievidue in colunm 2 ee^diiyinciraaeswideli operations dte^er 

is authorized to perform. Each operation subject to access control is 
associated with a value, called the access code, that is a power of 2. 
The sum of these access codes is the nominal value in column 2. 

Formally, the value in column 2 is the integer representation of a 
Boolean mask that has a bit fw each amtroUabte opetatioa. If 

MASK ^ {32p2 )tVALUE 

then MASKISZ-Nl (origin 1 ) is the bit regulating the operation 
whose access code is 2 * If the bit is 1 , the user is authorized f<x 
the q)eration. Many bit positions are not associated with any 
operations; the value of Aese bits is immaterial. Thus, ~ 1 grants 
authorization for every opoation, since <32p2)T~l ♦-► 
32pl . 

This last property is often used to grant all but certain kinds of 
access to a file, workspace, or library. The technique is to subtract 
from ~1 tie access codes for the operations to be denied. Fi»r 
example, ~5 grants all but UFERASE access ( ~ 1 - 4 ) , and "7 
grants all but □F£/?i4S£ and □fri£( "1- (4 + 2 ) ). 

• The passnumber in column 3 can be any positive or negative integer 
value. Together with the user number in column 1 , the passnumber 
determines which row of the access matrix is to be applied in 
verifying authorization for each operation. A single user or class of 
users can have multiple rows in the access matrix, with different 
privil^es granted with di£Fer»it pasaiumbets. 
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f^mAmss Matrix 

Suppose you want to set up a file to which all users have only 
' EFk^AB you want to be able to test the plication that 

accesses the file and obtain the same permission as another user. You 
would then set iq> an access matrix like this: 



0 


1 


0 


owner 


1 


0 


owner 


"1 


1234 



' Importance of the FitePaiMUHAar 



DFREAD-<xiiy access to all but owner. 

nFREAD-only access to owner. 

Full access with passnumber to owner 
so he can perform other file operations. 
Note that if the owner forgets the 
passnumber, he will be unable to do 
anything except a UFREAD unless he 
uses )FILEHELPER on the file. 



The passnumber used to tie a file remains associated with the file tie. 
After you have tied a file, you must supply the same passnumber in 
all subsequent operations on the file as you supplied when the file was 
d€Sf7USe of another passnumber will always produce a FILf 
ACCESS ERROR, even if some row of the access matrix happens 
U)^^nt t]^efq^»o^iate permission with that passnumber. To use the 

re-tie the S3e using tMt row's passnumber. 

'^^thangittg the Aeeess^Mairix When a FUe is Tied 



In the APL*PLUS System, access to an APL file is determined only 
when the file is ded. €eMiseqiietilly, dumging die aoce^ m&vAx of an 

APL file while it is tied has no immediate effect on access. The new 
value of the access matrix will be used when the other user uies to tie 
thefite;" - 



Similarly, if a user changes the access matrix of a file in a way that 
limits or otherwise (Ganges Us own access to the file, the change does 
not affect his access until the next time he re-ties the file. Therefore, a 
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•ebs^t to prevent accidental erasure by the owner of the file gives no 
protection until he unties or re-ties the file. 

Overri^ng an Access Matrix 

Under the rules of access control, it is possible to be locked out of one 
of your own files. Since the ability to set the access matrix is one of 
the opoations governed by the access matrix, you may be unable to 
correct the problem ^FSTAC alone. 

Facilities are available to assist the file owner who is locked out by 
the access matrix. The system command )FIL£^£LP£'£ enables 
the owno- to access the file and change its access matrix. Tlie syntax 
is: 

)FILEHELPER jUename 

where filename is a valid AEL file identifiv. See Cbs^ 2 of the 
APL *PLUS System Reference Manual tot detail on the use of 

)FILEUELPER. 

)FILEHELPER grants the owner full explicit access with no 
passnumber. The old access matrix for the file is discarded. You can 
then reset the matrix to an appropriate value. 

3-6 AFl mrmimi and VMS IHreet&ries 

A$L has traditionally grouped files and workspaces together in 
collections known as libraries, each identified by a library number. The 
VMS operating system organizes all of ihc files in the system by 
groining them into directories and subdirectories. This chapter 
ej^^iiiis how the AI1.*PLUS System fas WAX/VMS relates the 
VMS directories to APL lilnaries. 

VM5 Directories as Libraries 

A VMS directory can be made to appear like a traditional APL library 
by 0ni^ it a Iflbmy manb^. Ubmy numbers are associated with 

directories when the APL session begins according to the contents of 
the configuration file specified when APL is invoked. A line of the 
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APLn . INI7 ^e Jlnaiy number to be associated with the 
specific path. For example, die two-line file: 

y ■ "lifeiBStiy-llfapl. tools] 
■*.>'"• '^l^:5^ty-9123 [stuart] 



assoetates library number 1 1 with directory [APL . tools ] and 
Ubra^ number 9123 with [ stuart ] . A command of the form: 

yhOAB 11 ¥SDOC 

would then cause the workspace saved as [APL . TOOLS ] WSDOC . WS 
to be loaded. 

(!)nce the APL session is started, library definitions can be added using 
the syst^ fionction ULIBD . For example: 

ULIBD '244 IHARRISTl ' 

associates library number 244 with directory [harrlet] . 



When APL is in lilnary mode and a file identification omits the library 
number, a default value for the library number is the user's VMS 
account number ( 1 1 UAI ) . The default directory assumed is the 
current working directory in the VMS environment, as is set with the 
DCL command SET default. At session start, the working 
directory for the APL session is inherited from the working directory 
in effect when APL is invoked. During the APL session, the cutient 
w(»:king directtxy can be changed using the system function 



CHDIR ' LTEST. SCRIPTS! ' 
' • r-' WltKIl 

changes the current working directory to [TEST. SCRIPTS]. The 
" expillt^suftcortQiinsdmiiameof^ 

this point on, the library number that matches ( 1 1 DAI ) refers to 
that directory. 





Copyright 01987 S?rse, life. 



3-39 



Files 



You can use the system coRitngni )LIBS ^ Chapti^2 of the 

APL *PLUS System Reference Manual) or the system function 
ULIBS (see Chapter 3 of the APL *PLUS System Reference 
Manual) to display the library assignments in use for this session. 
You can distinguish whether the APL session is in path mode or 
library mode with D L IS S , which returns a zero-row result in path 
mode. 

3-7 Comparison of APL and Native Files 

You should compare the APL component files and the native files 
available through the APL* PLUS System in some detail. The APL 
files provide more automatic housekeq)ing and control and greater 
convenience when making changes. The native files permit an easy 
interface with non-APL systems such as word processois, ^ce these 
are the files that non-APL programs use. 

The native files created by UNCREATE are sequential Stream_LF 
files of the same type used by the VAX C compiler's run-time library. 

Fiks Are a Sequence tf Stand Data Item 

Both APL files and native files can be viewed as a simple se(|uence of 
suaed data items. They diff^ as foUows: 

• TheAH^fiteisa sap^ieedr AFLain^. Iik^ array, independent 

of the others, can be of any datatype, of any rank, of any shape, and 
of any size. One can be a table of decimal numbers, while the next 
can be a four-page memo. Regardless of the nature w die of the 
array, it is referred to by a single component number and can be 
retrieved by that number. When a component is retrieved, the array's 
internal organization (the number of bytes per element and the 
interpretation of the arrangement of the bits, known as datatype) and 
external organization (shape) are recognized and handled 
automaticaily. 

• The native file, by is a sequence of bytes (one character's worth of 
data). How those bytes are organized or what they represent is 
detomined ratirely by the pro^ammer. This represents maximum 
flexibility at the cost of maumom programming effort. The 
program performing the retrieval must deal with where to start 
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- Tei^f the inMgFial, how-to read bdbieiea^^ 

^i w v . . . : . . ' whether to eCaiirart to numeric form (and which numaicfom 

. whether to le^iagpe the data and how. 

Space Reservation and Cheeking 

'. ■ -r' P-l:'*" : ,: . .^.^'^.K.l^i^^jile can be given a size limit. Each time you attranpt to add 

; > . or replace material in the file, the system automatically checks whether 

the operation would cause the file to exceed the limit. If the limit 
would be exceeded, die operation is not performed. A FILE FULL 
is signaled, and the programmer (or die program) must deal with that 
condition before continuing. This permits budgeting of disk space and 
5^ :! . , \ . (M r.. ?.o leeogaii^ of "nmway" iffiQgnuns. 

b:v. • ' r. :S' "There is no such size checlong in Writing to 8 luitive fiUle. 



Ownership and Access Control 



The APL*PLUS System tracks the user account number diat created 
or last renamed the file (its owner). Through the use of the access 
maic^ die file owner and fiiose individuals he specifies can extend or 
limit the types of file operations that can be performed by any given 
user account number. The use of non-zero passnumbers in the access 

can be restricted to Iddced APL fuiKdons or q)ecial kinds of ^ 

Access to native VMS files is controlled by a less specific mechanism. 
Each native file has a set of "permissions" that determine how it can 
be used and by whom. The three permissions are: 

, • F«a<ipeimission - the privilege to read any data that the file contains 



-j. •. nL . '-^ T -.f- . -'tci r - . • write permission - the fwivilege to modify the file or oase it 

. ■ ' ' completely 

• execute permission -- the right to attonpt to load and execute the file 
as an executable binary program. 

■ ■. '■•Ml..- . ' 

Rather than track distinct permissions for each user in an access 
matrix, the VMS operating system recognizes three classes of users: 
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• theowno' 

• the members of the owner's group (a concept that is not used in APL) 

• everyone else. 

The VMS operating system tracks each of the three classes of 
permission for each of the three classes of users. The system 
fimcdons UHRDAC md ONSTAC mi be used to read and modify 
native file permissions. See the detailed description of these features 
in Chapter 3 of the APL *PLUS System Reference Manual. 

Reptaetmm afDm 

You can replace one component in an APL file with any other APL 
array using DFREPLACE. You need not match the physical size in 
bytes, the datatype, or the shape of the array being replaced. In a file 
with 2 0 components, you could replace die integer in component 7 
by a huge table of numbers without stopping to ask how much room 
on the file the integer occupied: 

ASTRO QFREPLACE 5 7 

ConsequenUy, it is extremely easy to replace an object with an 
enlarged (updated) vo^on of itself; for example, a customer list with 
one otmsxt new casmieis added. 

In a native file, you €101 eidy replace data byte-for-byte. You (or the 
program) ttml how large tihe amount of data to be put into the file 
is, and how that compares with the amount already there. Other 
questions you should ask include: Where does the data that is already 
diere begin? What information currently in that space will be 
destroyed by a simple byte-for-byte replacement? Will space be 
wasted? Is more space needed than is used by the data to be replaced? 
If SO, -irbmt else can it be pot, or how can a larger vetakm of this file 
(ok that has more loran for die iqdacemoit) be created? 

Qeariy, an \sp6mi list ot oAerwise eidnged ot^ cannot simply 

replace die earlier version on the file. TopBSSNve the same relative 
position would entail copying die rest at tte file widi the new data 
into a new file. To avdd copfiag of all the data, you must set up 

some sort of directory system to track the data. This can include 
currenUy unused space abandoned as data grew. If unused space is not 
tracked, it cannot be reclaimed. 
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If an APL file is cramped for space, reclaiming wasted space is simple. 
The system function UFDUP uses the inienial component-tracking 
data to compact the file dom to cmly its tiseMdiaii. 13^gQFDUP 
requires that enough space be availabte on the disk to hold all the 
confuted data. 

Since native files do not predictably include such tracking information, 
no compression of space wasted in native files can be provided by the 
^^ton; it must be provided bjf Ae pi@panmer. 

Timestamp Information 

For each component, an APL file stores not only the data, its shape 
and datatype, but also, (retrievable separately with UFRBCI) three 
other pieces of inftmnation not tiadced by native files: 

• how big it is (the number of bytes of workspace storage that would 
be needed to lead die ansy) 

• who stored it thoe (the user account number that put this array in 
the file) 

• whenitwasst(»ed^dittBimdfimeracodedim0ai^n(|^niik 
called a dme^an^). 

The syntax of DFRDCI is: 

result *- UFRDCI tieno compno 

Different Naming Conventions 

The names of APL files are restricted to combinations of a^habetic 
and numeric characters, while the names of native files can contain 
other characters permitted by VMS naming conventions (see your 
VMS operating system manual) and are not restricted to names 
beginning with a letter. 
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Formatting Data in the APL *PLUS System 



This chapter describes the formatting capabilities of the APL* PLUS 
System function QFMT and identifies the formatting functions 
jivaflable to the wi^pace FORMAT. 



4*1 Designing A Bepart. 

The first step in generating a report is designing it. Consider several 
fi^ttss heion yoa fyaoat the data for your report: 

- • the ordo' of the columns 

• the representation of the columns (intega, decimal, pattern, 
exponential) 

• the width of the columns 

^ J v'^fiAAc^^diieeBt^iqiorL 

You also must decide what kinds of decorations you want to use to 
darify the meaning of the data. For example, you may want to 
include dollar signs, commas, negative signs, and so on. In some 
casKS, a pmm 'may be tfiebest w^qr to represent to diEBi^ ftff ample, 
a telephone number can be displayed with parentheses around the area 
code. The diagram below shows what the structure of a typical report 
ought lQ(^)|iQB« 



Design of a Typical Report 



THIe 
Subtitle 



Column Namas 
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Once yotf have -dedded on die basic layotii of ymt repm, use die 

functions described in Section 4-14 to add and position titles and 
labels. The following report is an example of what a typical report 
taij^bt iodE fifce uaoig die structure shown in Exhibit 4-1. 

SASSIS GARAGE 
EASTERN DIVISION INVENTORY REPORT 



PART NAME 


NUMBER 


QUAN 


PRICE 


VALUE 




REORDER <6M0 


BATTERY 


Q 1 Ci 

0 /y 


A 1 

-01 


492 


$92.85 


$45,682. 


20 


1O/10 / Q 1 

I Z / I 6 / o 1 




CARBURETOR 


t C T 

bo / 


-04 


769 


$73 . 23 


$56 , 313 . 


87 


6/06/87 


D 
K 


FUEL TANK 


876 


-03 


371 


$71 . 80 


$26, 637. 


80 


6/24/8 / 




WHEEL 


234 


-06 


287 


$41.76 


$11,982,25 


4/12/87 


n 
K 


BATTERY 


0 /D 


«.m 
-o / 


381 


m.45 


$36,747. 


45 


9/ UO/ O / 




TIRE 


876 


-02 


98 


$60.90 


$5,968. 


20 


4/25/87 


R 


AXLE 


265 


-07 


205 


*55.85 


$11,449. 


25 


11/13/87 




TIRE 


361 


-08 


387 


$66. 95 


$25,909. 


65 


9/26/87 




BRAKE 


876 


-06 


201 


$32. 00 


$6,432. 


00 


3/01/87 


R 


CARBURETOR 


876 


-04 


879 


$157. 80 


$138,706. 


20 


6/25/87 




TIRE 


234 


-01 


298 


$68 . 90 


$20,532. 


20 


2/11/87 


R 


EXHAUST 


876 


-05 


367 


$354 . 00 


$126 , 615. 


00 


6/25/87 




IGNITION 


876 


-09 


652 


$22. 50 


$14,670. 


00 


3/12/87 


R 


SPARK PLUG 


273 


-03 


391 


$2.85 


$1,114. 


35 


8/05/87 




RADIATOR 


872 


-05 


738 


$63.80 


$47,084.40 


2/28/87 


R 


WATER PmP 


Z&i 


-69 


276 


tS3.7t 


$14,843. 


28 


9/08/87 




ALTERNATOR 


729 


-07 


493 


$96.70 


$47,673. 


10 


7/14/87 




RADIATOR 


316 


-02 


387 


$69.30 


$26,819. 


10 


10/26/87 




COIL 


582 


-08 


492 


$25.50 


$12,546.00 


1/21/87 


R 



fiiastepatt uras produced widi the foOowiBf jptopain, called INVENT 0 R Y. 
The program uses the system function UFMT and several functions hom tiie 
FORMAT workspace. 

y INVENTOR Y ; COLNAME ; DATE ; FSTR ; NUM; PRICE ; QUANT ; RN ; VALUE 
cn fSrjf-'13i41,ri6,G<Z99-99>, 16. r29, P<*>f8.2, 138' 

[2] FSTR^FSTR.' .CP<$>FIZ.2, 151, G<Z9/99/99>' 

[3] FSTR^FSTR.' ,N< R>Q< >I13, X~13, 5< >' 

[4] NUM^ 87901 65704 87603 23406 87607 87602 

[5] NUM-NUH, 26507 36108 87606 87604 23401 87605 

C6] NUM^NUM, 87609 27305 87205 25109 72907 31602 58208 

[7] RN^' /BATTERY/CARBURETOR/FUEL TANK/WHEEL/ BATTERY ' 

[8] RN^RN, ' /TIRE/AXLE/TIRE/BRAKE/CARBURETOR/TIRE' 

[9] RN*-RN.> /EXHAUST/ IGNITION WIRE/ SPARK PLUG/ RADIATOR' 

tlO] RN'^RN,' /WATER POMP/ ALTERNATOR /RADIATOR/ COIL' 

Cll] QUANT- 492 769 371 287 381 98 205 387 201 879 298 

C12] QUANT-QUANT, 367 652 391 738 276 493 387 492 

[13] PRICE- 92.85 73.23 71.8 41.75 96.45 60.9 55.85 66.95 
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[14] PRICE^PRICE , 32 157.8 68.9 345 22.5 2.85 63.8 

[15] PRICE^PRICE , 53.78 96.7 69.3 25.5 

[16] DATE^ 121383 50683 62483 41283 90383 42583 111383 

[17] DATE^DATE, 92683 30183 62583 21183 62583 31283 

[18] DATE-'DATE. 80583 22883 908-83 7i4S3 102683 12183 

[19] VALUE-^QUANT^PRICE 

[20] COLNAME^WPART NAME/NUMBER/QUAN/PSICE/VALUE' 

[21] COLNAME^COLNAME.' /SM0RDMS/<6 MO.' 

[22] OLNAME*-FSTR COLNAMES CmMAM 

i«^,,'/.-f vv--.,-r>i- [23] ffi^-(iO) ROWNAMES RN 

•.!- ,;-.• , ; v.. ! - [24] FSTR RJUST '1/5/87' 

[25] FSTR CENTER 'HARRIS GARAGE' 

[26] FSTR CENTER 'EASTERN DIVISION INVENTORY REPORT' 

[27] • ' 

■' ■ ' [28] COLNAME 

[29] ' ' 

[30] FSTR QFMTlRNiNUM;QUANTiPRICEiVALUE;DATE:»DATE-6Q5ST) 

■1; , .. . ■ yi 

The program defines a format string containing fonnatting 
Instructions, assigns the data vari^tes, rm& the title functions and 
column and row name functions to set the titles and label the rows and 
columns, and finally calls QFMT to format the data into the report. 



4-2WhaiIsnFm'? 

The system function DFAfr is a simple, economical, and adaptable 
tool for detailed tabular formatting. UFMT allows you to: 

• format several data arguments at a time 

r , ,. :•> ' • vary the prmting order of cdumns of data from the normal 
left-to-right ordo: 

• display tables of numbos in designated rows and columns 

., , , ^ • decorate monetary values with dollar signs or other identifiers 

<' ^|»!E^ tt@ iesBto of floating-point calculations as Standard 
_ decimals or &i{esg€i§ 

• place flags to mailc negative or zero values in results. 
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UFHT is a dyadic system functicm. It can be r^resented as eithen 
result*- 'Jbmuostting' UFMT data 

at 

result ■<- 'formatstring' UFMT idatal '.dotal \data3 \ ... ■.datan) 

The left sr%\mtnuformatstring, is a character vector that specifies 
how you want the data to look. It contains specific formatting 
instructicNi^ttait COtmi^ Use editing and display of the dgtat argument, 
the data you want to format. A data item in the right argument can be 
the name of a variable or an APL expression that produces a result. 

The result of UFMT is always a character matrix. It can be stored and 
used within a larger expression like any other APL expression. For 
etample, the result of the e^qpressicm: 

•14' UFMT 987 

is a osnBrtcrn, four-column character matrix containing the value 
' 987». 

The number of rows in the matrix result is determined by the 
maximum number of matrix rows or vector elements in the data. The 
number of columns is determined by both the format string and the 
right argument 

The length of an edited line is limited only by the workspace storage 
required to hold the values. The value of DPI/ does not control the 
length of the line, and the value (tf OPf does not a^t precision. 

4-3 Right Argument -The Data List 

The right argument to UFMT is a data list containing APL variables, 
constants, or expressions that return numeric or character scalars, 
vectors, or matrices. A single data expression in the right argument 
needs no paroitheses; for example: 

'formeustring^ UFMT data 
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>-»IF^tt^ii^t argument ccxitains two or more data expressions, you can 
separate them with semicotons, and oictose the entire set in 

parentheses: 



ing' QFHT (.dotal ',data2',(lata3; ... idatan) 



or you can use strand notation to specify die data as a n^ted atiay: 

' formaistring ' UFMT dotal dotal dataS . . . doton 

You can replace any item in the data list with an expression that 
ivoduces the desired value as a result (though you may need 
parentheses). The foIk)wingeKanq>]es show scHneporniissiUe right 
aiguments: 

SCALAR - 15 

VECTOR ^3.5 AE3 0 . 007 1 
CHAR - 'MONDAY' 
MAT ^3 4 pi 12 

. *fmuitsttwg* DFMT SCALAR 

'formamiKg^ OFMT 2 2 pVECTOR 

'formotstnng ' UFMT ( SCALAR ; VECTOR ; CHAR ; MAT ) 
'formaistring' QFMT SCALAR VECTOR CHAR MAT 

'formotstnng ' QFMT (MAT;* /MAT) 
'fortnatstring' QFMT MAT (*/MAT) 

The AH^aFIjIIS System fonnats data e;ipressions of differrat shapes 
as follows: 

.* A matrix has each column formatted separately. 

• Ave^istiealedasaone-coliBiminatrix. 

• A scalar is treated^ a one-row, one-column matrix. 

If you want to display a vector horizontally, reshape it as a cme-tow 
matrix. 
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Each column of data (which can be one scalar, one vector, or one 
column of a matrix) is formatted individually as q)ecifi6d by the left 
argument. 

4-4 Left Argument -The Format String 

The left argument to □ FMT is a character vector containing one or 
more format phrases. There are two classes of format phrases: 

• Editing format phrases edit data in the right argument; for 
example, the I format phrase displays numeric data in integer 
fwmaL 

• Positioning and text fonnat phrases change the appearance of the 
result without editing any data; for example, the T format phrase 
q)ecifies tab stc^s for column plxement 

You can also use special parameters with many of the format 
ghiases to specify the field width and precision of the image, and you 
<sm use modifiers to add i^iiecial ^ects. 

Separate individual fonnat phrases with commas and enclose the entire 
string in single quotes (the phrase must be character-valued). You can 
use the format string directly as a character vectOT, or you can ^uxt it 
in a variable and use it later. 

•14' UFMT V 

or 

f - '14' 
F UFMT V 

TextDettmiters 

Place text in the left argument between pairs of delanitMS. Any of Ihe 

pairs of delimiters shown in the following list are valid. The closing 
delimiter must correspond to the opening one. 
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A.. : .: Dtelimitm ' . - J&iamples 

< > <19 > 

to M _ 

on D-D 

■ '^yy /NO/ 



You can use any of the delimiters as text characters within a format 
phrase; but one of them cannot be die closing ddimiter. For example, 
to use the characters 

§>37 

as lect in a fooaat phrase, ycra could enclose Aem 
delimitos: 

Bow Uw Format String is Processed 

The format string is scanned phrase-by-phrase from left to right 
Iditingfonnat phrases are matdied wift edi^^ 
positioning and text phrases are processed as ib^ are ^couQtcsed 
without reference to the data. 

You need not provide the same number of format phrases as columns 
of data in the right argument The number of format phrases does not 
> hiv&td'divtde the number of columns of data evenly. If the fonniat 
string contains an insufficient number of phrases to edit all of the data 
in the right argument, UFMT cycles through the format string 
R^e{tte% until aU of die data has been e^M< tf the taiat stting 
contains more phrases than are neCGSsaiy to edit all of die data, the 
trailing phrases are ignored. 

Spaces in the format string have no effect, except between text 

delimiters. 



Fonniitting 



4-5 How to Construct a Format String 



A format string comprises several parts: 

• Fonnat phrases edit and position text and data. 

• Vazmems, m used with fcmnat phrases to give QFMT detailed 
instructions. 

• Modificos add iq)ecial effects and decnations to edited data. 

For example, in the format string 
CI13 

I is the format phrase telling UFMT to format numeric data as 
integers, 1 3 is the parameter to the I format phrase specifying a field 
width of 13 cokmn^ and C is a modifiar specUying that commas 
i^iould sqptate eveiy three digits in ^ data. 

Uq eonstniet a tatat string, determine a repm width and the width of 

individual fields within the report. Then select appropriate format 
phrases for the corresponding data, and code the required parameters, 
saebfis field i^th mi ttie ntoittjer irf (£fits to be displayed. You c^ 
also include modifiers and decorations for special effects. Add 
positioning phrases to the format string to control the location of 
fields. 

Simplify the coding of repeated fomiat phrases or groups of format 
j^hrtffies by using repetition factors withni par^&eses. A li^tition 

fieBlMris anon-negative integer indicating the number of times to 
'i^l^i^ldu'ase or a group of phrases. The default repetition factor is 1 . 

You may find it helpful to store format strings as variables, especially 
if you will be using them with several different right arguments. 
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4-4 The E^ng Format Phrases 



The A, I, F, E, and G fonnat phrases place columns of data in Ihs 
ligjit aisument into conespon^ng fiel^ in the result 

A » Character Editing 

The A fonnat phrase is the only phrase that edits only character data. 
The 4 phrase lakes ttie fionn: 

Aw 

where w is the field width. The fidd width specifies the number of 
columns in the result to be occupied by the edited value. (Remember 
■tstt^k^icior is treatedis a 01^^ 
single column, unless it is lesbqped to a one-row mittrix.) 

>' = / 

•Al' OFMT 'SALT' 

S 

L 
T 

A character matrix in the data can contain several columns. In that 
case, you must specify a separate A format phrase for each column. 

CMATRIX "^14 p'SALT' 
*MU1.A1,A1' UFMT CMATRIX 

SALT 

Instead of typing the format phrase repeatedly, you can use a repetition 
factor to repeat the phrase. In the following example, a repetition 
famr&f^isvseA. 

• 4A1 ' UFMT CMATRIX 

SALT 

When the same fonnat phrase is used to iht entire right argument, as 
in the above example, you can omit the iq)etition factor. 

Ml' UFMT CMATRIX 
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If the field width is ^ieater than 1, leading positions of the field are 
filled with blanks. 

VORDSQ - 3 3 p'BOAURNSEQ' 

Ml, A2. AS' UFMT VORDSQ 

BOA 
URN 
S E Q 

'A2. A2. A2* QFMT WORDSQ 
BOA 

URN 
S E Q 

If you try to use an A format phrase to edit numeric data in the right 
argument, the result field is filled with stars (*). 

'A6' UFMT 133 
****«"* 

Stars also result if you try to use an edit phrase other than A to edit 
character data. 



'14' QFMT 'ABC 

* * * * 

* * * * 

* * * * 



J - Integer Editing 

The I format phrase edits numeric data in integer format The I 

phrase takes the form: 

Iw 



wfa^ wis the field width. An J fionnittiAuasedE^lays numeric data 
as integers. Be sure to include.s|Hce fat die field width for negative 
signs in the result that correspond to negative values in the data. 

TABLE - -3 2 "1 •.* "2 "1 17 
TABLE 

0.1111111111 -0.3333333333 "3 "2 187 
0.25 0.5 2 128 
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•314. 16' QFMT TABLE 

00-3 "2187 

0 1 2 128 

1 "1 "1 -1 

A. '18' UFMT (3x4), 6£2 0.4 476.85912 

• -o 12 
600 
0 

477 

^ feiniat. The F phrase t^s the form: 

Fw.d 

■ " ■ ' where w is the field width and d is the number of decimal positions. 

For example, the format phrase F9 . 2 creates a field of nine 
positions, in which every value is formatted to two decimal places. 
Allow two positions in the field width for a possible negative sign and 
a decimal point 

'FS.2< DFMT TABLE 

0.11 "0.33 -3.00 

0.25 0.50 2.00 

1.00 -1.00 -1.00 

'• - Pornumbm between "1 and 1, a zero is placed to the left of die 

decimal point in the result. Dyadic format, in contrast, displays such 
numbers without a zero to the left of the decimal point in fixed-point 
ecfiting. 

E • Exponential Editing 

■ ' ' ■' The E format phrase edits numeric data in exponential (scientific 

■ Au-i-'. Mi notation) format. The f phrase takes the form: 

,EWiS^ 

where w is the field wMth and s is the exact number of significant 
figures in the nonej^cment part of the result. For example, the format 
phrase £15.7 pn^uoes a field width of 15 with 7 significant digits. 
The number of significant digits Rifled must be between 1 mi 16, 



"2187 . 00 
128.00 
-1 . 00 



Mi 
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inclusive. The widlh must be at least sev^ nmt than die nuntb^ of 

significant digits to provide space for a negative sign, a decimal point, 
and a five-position exponent of the form E ~nnn. Additional widlh 
leaves visible space betweoi columns. 

•£10.2' UFMT TABLE 

-3.3f-l -3.0£"0 -Z.ZfS 

2.5£-l S.Of-l 2.0£0 1 . 3£2 

l.OEO -l.OfO -l.OfO -l.OfO 

•£12.4' npHT 2*50 "SO 
1. 126£15 
8.882£-16 



G- Pattern Editing 



The G format phrase edits numeric data according to a pattern or 
picture format. With this phrase, you can arbitrarily mix text 
eharaeters mid data ni a fermatled cohnnn by oeatinga pictorial 
template for the data. Special characters within the pattern indicate 
where to display digits in the data; other characters are displayed as 
they {p)ear in the pattern. The G phrase tdces the form: 



G<patlern> 



vAxBCt pattern consists of the special characters 9 and Z, called digit 
selectors, along with other text characters to insert in the field. Use 
any valid pair of text delimiters to enclose the patt»n (see Section 
4-3). Vat example, to format a date with a G pattern, enter 



'G<99/99/99>' UFHT 11887 
01/18/87 

The number of characters, including blanks, between the pattern 
delimiters determines the field width. The field is formaued with the 
exact numbCT of characters and digits specified in the pattern. 



Data in the right argument is rounded to the nearest integer. Each digit 
(tf the integer is transfmed to the field to replace a digit selector (9 or 
Z) in the pattern. A 9 in the pattern transfers the corresponding digit 
from the integer into the result. A Z suppresses leading and trailing 
zims, ttansferring the corte^pQltd£ag ^gii only if tte digit is nonzoo 
or if it is between two uansfimed digits, as described below. 
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'^is tiie iS digit sdector te^it leading or trailing zeros in the edited 
fields. If a Z corresponds to a zero in the integer, the zero is 
transferred only if digits on both sides are transferred; otherwise, the 
corresponding position in the field is unchanged. Since a 9 always 
transfers a digit to the result, a Z between two 9 s acts as a 9 digit 
selector. For example, G<Z9Z.99>is equivalent to 
G<Z99 . 99>. ThefoilovvingsMecQtoiiaiss Ae^ect$o 9s 
and Zs as digit selectors: 

Fonnainurase Data Residt 

G<Z99.99> 2460 1200 0 24.60 12.00 OO.OO 

G<Z99.9Z> 2460 1200 0 24.6 12.0 00.0 

G<ZZ9.9Z> 2460 1200 0 24.6 12.0 0.0 

G<ZZ9.ZZ> 2460 1200 0 24.6 12 0 

LZZ> 2460 1200 0 24.6 12 



You must insert text characters or Z digit selectors in the pattern to 
display negative signs and decorations (decorations are explained in 
Section 4-10). Leading and trailing text characters always transfer 
directly to the result. Text between digit selectors transfers only if 
digits to. the right and to the left of the pattern text are transferred. 

Compare tiie anpemmi^ fBimos m&ismmm in ^ two 



.. HUM 298738472 389487.987 387 0.35 
ZMES - •G<$ ZZZ.ZZZ.ZZB AND HO CEllTS>< 
NINES 'G<$ 999,999,999 MD NO €MNTS>* 

ZEES UFMT NUM 
* 298,738,472 AND NO CENTS 
$ 389.488 AND NO CENTS 

$ . -• . 387 AND NO CENTS 
t " 0 AND NO CENTS 

NINES DFMT NUM 
$ 298,738,472 AND NO CENTS 
t>,PP!?-ft389.4S8 AND NO CENTS 
i'Wfr00©.3t7 AND NO mNTS 
t 000,000,000 AND NO CENTS 

You can use G formatting to produce visually effi^tive reports when 
numbers are displayed in traditional patterns. 
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EltPW •-4 7 p'MML 0Xf.OIS MUSS ZORN ' 
5SV*-2f8374562 2987$0I8S 3l47ie4S3 273069857 
m-4086729873 7187364782 8063S4t726 3138472637 

SALES *- 567 309 4958 312 

SAL - 49800 50000 59500 41200 

FS - '7X1, G< 999-99-9999 >.G< (999) 999-9999> 
FS *■ FS, ' .I6.{?< ZZ. ZZ9>' 

FS QFMT (EMPLO;SSN;TEL; SALES; SAL) 

ABEL 298-37-4562 (408) 672-9873 567 49,800 

GALOIS 298-75-0385 (718) 736-4782 309 50,000 

GAUSS 384-71-6453 (806) 394-8726 4958 59,500 

ZOM 273-06-9867 (313) 847-2637 312 41,200 

Although data values edited by a G format phrase are rounded to 
integers, fractional values in the data can be displayed by multiplying 
thedatabytiieaiqxopdatepowreroftni. InUief(dlo«d0f eigKHtple, 
the data is multiplied by 100. 

MONEY - 1 4 pl4.e 52 17 2.44 

'ff< $99.99>' BFMT 1QQ>^M0NEY 
$14.60 $52.00 $17.00 $02.44 

A better way to ac^iieve tibe same ^ieet is t9 

phrase with the K scaling modifier (see "K - Scaling" in Sectitm 4-10). 
In the following example, the data is scaled by 1 0 * 2 . 

'K2G< $99.99>' DFAfT MONEY 
$14.60 $52.00 $17.00 $02.44 



4-7 The Positioning and Text Format Phrases 

The positioning format phrases allow you to position fields without 
having to count individual positions. The positioning phrase specifies 
the column where the result of the next format phrase should begin: 

• The T phrase specifies the starting column relative to the left margin. 

• The X phrase ^ecifies the starting column relative to the current 
position. 
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The <text> fmm jploaselttseAS text diiecfty imo Ae result field. 
These thisee phrases do not edit data; they siiiq>ly positicm it in the 

result 



T -Absolute Tabbing 



^e T phrase spedfi^ ilK»lute tid)bing (jumping to a particular 
column). It takes Ae form: 

Tp oar r 

where p is the column position (counting from the left margin) at 
which to fcxrnat the next edited value. For example, T 1 5 moves 
directly to position IS regardless of the previous position. The first 
available position on a line is T 1 . 

If you use T without specifying the position, the next field is 
formatted to the right of the rightmost coluiim of the result formatted 

•3iil, no. 12* IIFJW (1 3 pTiW'-.lO) 
TAB 10 

Using a T phrase before individual format phrases can make the fiumat 
string easier to modify. The position of a field is clear and is 
independent of previous fejmttMq^ laitruaic»i& 



X - Relative Tabbing 

The X phrase specifies rdative tabbing, or positi(»is to be skqq)ed. 

takes the form: 

positiQ&;|befote formattiQg die next fidd of the result 

, V • If ;>kix)8itive,pist]ienomberofpositifflistobesiEqped tol^^ 

• If p is negative, p is the number of positions to move left 

• If p is zero, the phrase is ignored. 
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Specify a negative value wi& & negative sign (X ~ 1 2) or a minus sign 
(X-12). 

'I12.X-12,2I4.3E4.i4' QFHT 1 4 pi 2 3 4 
2 3 14 

<text> • Texttmet^n 

The <text> phrase inserts the text between the delimiters into a line. 
The phrase takes the form: 

<text> 

where text is any combination of characters and spaces. All &ie text 
between the delimitas, including blanks, is mserted directly into the 
edited ttne. You can use any valid pair of text delimiters to enclose the 
text (see Section 4-3). 

DPT ^ 3 4 5 

REV - 344.50 89.74 250.13 

FS-^' <REVENUES FOR DEPT.>,I2,< ARE . . t> ,FG .2' 

FS DFMT (.DPT; REV) 

REVENUES FOR DEPT. 3 ARE. .$344.50 
REVENUES FOR DEPT. 4 ARE . . $ 89.74 
REVENUES FOR DEPT. 5 ARE. .$250. 13 

Using PosttMng and TextPhmses 

You can use the f and if Satmt to po^coi Sekis without 
having io count individual spaces. In the fonhat string : 

15, X3, 25/1, rSl. 4F7.2 

the first floating point field begins in position 51, and if all four F 
phrases are used, the result is a matrix with 78 (6 0 ♦ 4 « 7) columns. 

Positioning phrases may re-order data in the result. This example uses 
paienth^s and repetition factors to simplify the left argumm (see 
Sections 4-8 and 4-9), 
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■■P'S'*- *iiAl, <- >). n. 3(I3.X2)' 
FS UFMT (3 Sp'ABCDEFGHI' -.3 3pl9) 

A-1 B-2 C-3 
Z?-4 E-S F-6 
G-7 W-8 1-9 

You can use text phrases to ovaaiie previously formatted fields. The 
decimal point is replaced by a colon in this example. 

FS - 'f7.2, X-3, <:>, T' 
FS UFHT 1 4plO+0. I5x-l*l4 
10:0.0 10:15 10:30 10:45 

You can use symbol substitution to achieve the same effect (see 
"S - Standard Symbol Substitution" in Section 4-10). 

A backward-pointing relative or absolute tab may cause a previously 
formatted field to be overlaid by a new field. This new field need not 
mibsh die' wfift or^gnment of any jseviotisly finmatted field. In 
this case, nonblank characters in the new field replace the 
corresponding characters in the old field. Blank characters in the new 
fidd ^BSi occotr as lesult of eiq>licit mendcm in <ma> lihrases, G 
phrases, or certain modifiers also replace the corresponding characters 
in the old field. However, blanks used as fill characters do not replace 
any cbaracfers in the old field. 

In the following example, the background fill modifier R (see "R - 
BackgraandKIl" in Section 4-10) dters the ncmnal blank background 
fill chaiacter. 

IOTA - 1 4 pi 2 3 4 

'112, Tl, 214. r. 14' nFMT IOTA 

2 3 1 4 

•fi<'>112. Tl, 214. r. 14' QFMT IOTA 
...2.*.3...1 4 

*fi<»>112. ri. ZR< >I4. T. 14' UFMT IOTA 
2 3»'»1 4 

In die last examptei Hie blanks in the rightmost t aio^er ovmide 
previously formatted fields because they are text characters rather than 
fill characters. 
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You can use special parameters within format phrases lo give DFMT 
detailed instructicms. Use them to specify: 

• the number of times to apply a phrase or a group of phrases 

• the width of an edited column 

• the number of digits to be displayed 

• the position for a tab or skip. 

Most parameters specify essential formatting considerations and are 
required with their corresponding format phrases; however, repetition 
factors are optional. Repetition factors improve the readability of a 
format string containing repeated fonnat phrases and often clarify the 
structure of the format string at a glance. They are useful when a long 
fionrnt phiase is needed. 

w - Field Width Parameter 

The field width parameter w determines the number of positions in the 
result to be occupied by the edited value. It is required with the following 
Itaises: Aasia Aw, E ts in Ewj,F as ki Fwxt, and I as in Iw. 

•F6.1. F12.1. FB.l, F18.1' DFMT 2 4 p58.8 
58.8 58.8 58.8 58.8 

58.8 58.8 58.8 58.8 

ANAGRAMS - 6 4 p' OPTSPOSTPOTSSPOTSTOPTOPS' 

'Al' QFMT ANAGRAMS 

OPTS 
POST 
POTS 
SPOT 
STOP 
TOPS 

If die field width is greater than die number of digits or charactm, the 
field is padded with leading blanks. 

'A2' UFMT ANAGRAMS 

OPTS 
POST 
POTS 
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. SPOT 
STOP 
TOPS 

Be sure to leave space in the field width far. 

• ai^ej^^signinanf.F.a Jphrase 

• a decimal point in an F phrase, or in an f phrase ifimae than one 
significant digit is specified 

• an exponent of thefiarmfimn in an £ phrase 

• ipy spacing you might want between the columns of a matrix. 

If the field width is miinifBcient. the fidd is filled witii stats (see 
Section 4-12). 

TABLE -3 2 -1 •.* "2 "1 17 

•rS,!' Of Mr TABLE 
0.1 "0 . 3***** 

0.3 0.5***** 
1.0 "1.0 "1.0 



d - Decimal Position Pantrnter 

Tbe decimal position parameter d controls the number of digits that 
appear to the right of the decimal point It is required with F phrases 

(FlV.£0. 

FS *■ 'F2.0. FT. 3, flO.6. F13.9. fl6.12' 
FS QFMT 1 5pol 
3. S.142I 3.141593 3.141592654 3.141592653590 

5 - Sigttffieant Digits ParameUr 

The significant digits parameter s contids the number of significant 
digits in the nonexponent part of the lesult. The value of this 
parameter must be at least I. This parameter is required with E 
phrases (Eyyj). 



• , ■; 'Kill/,- ■••»* I-'- >!-vv i 
J I,.', hix :ti<i <::,''< i.i 

-.1 ,ri' tiSStij :. ,11, '. / • 
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'£10.2. £9.1, £17.9' DFMT 1 3 p-57. 98765 
-5.8£1 "6£1 -5,79876500£1 

<pattem > • Pattern Text Parameter 

The pattern text parameter < pattern > provides detailed control over the 
location of the individual digits of the value to be formatted. It is 
required with G phrases (G<pattern>). See "G - Pattern Editing" in 
Section 4-6 for detailed information on this parameter. 

p - Position Parameter 

The position parameter p controls the location at which to display the 
next field. It is required with X phrases (Xp) but is optional with T 
phrases (Tp). When used with an X phrase, p is the number of 
positions to be skipped from the present position. For example, 
because X 1 says to skip the Hrst position, it specifies the second. It 
can be a positive or negative integer, or zero. A zero causes the phrase 
to be ignored. Specify a negative value with eitha a negative sign 
(X ~ 1 2) or a minus sign (X - 1 2). 

When used with a T phrase, p is the number of positions from the left 
margin and is always a positive integer. For example, T 1 indicates 
the first position. 

•112. 4(X-4. II)' QFMT 1 4 pl4 
4 3 2 1 

Fs - '712. II, 19. II, re. II. r3. ii' 

FS - nFMT 1 4pi4 
4 3 2 1 

r - Repetition Factor 

The optional repetition factor r determines how many times to use a 
single format phrase or a group of format phrases enclosed in 
parentiieses. You can use it with any format phrase. The repetition 
factor precedes all other elements in the format phrase. For example, a 
repetition factor of 2 to the left of an editing format phrase causes that 
I^aSe l@> edit two successive columns from the data list For 
example, F6 . 3 , FS . 3 isthesameas 2F6. 3. 
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. , Af^onzcTO repetition factor to the left of a T phrase has no effect. Fcff 
,€31^1^. 3 r 5 is die saiae as r 5 and 3 r is the same ^ r. 

A mtasto repetiion factor to the left of an X phrase repeats the 
specified skip. For example, 3X5 is the same as X 1 5 and 3X ~5 is 

the same as X~ 15. 

. , . A BDnzero repetition factor to the left of a < text > phrase repeats that 
phrase. For example, 2<PAG0 > is the same as < PAGO PAGO 

A zero repetiticHi factor to the left of any phrase causes that phrase to 
be ignored. 

The defaidt icpetitoi factor is 1. 

i^r^ping Symbols 

Useparantheses in the left argument of UFMT to simplify the 
consthKtion of repeated sets of format phrases and to limit further 
scanning of die fonnat s^g "^en the da^ has been exhausted. 

Enclose the group of format phrases in parentheses and place the 
n^l^^Sfion factor to the left of the left parenthesis. 

12A1. 4{fl0.2. 14) 
J15. 4<X-4. 11) 

""' Without parentheses, you would have to specify the second format 

string in the preceiteg tstample as: 

115, X-4. II. X-4. II, X-4, II, X-4. II 

.1 1 A zero repetition factor to the left of a leftpirenth^s causes the 
passes in the group to be ignored. 

If parentheses are used and no i^tition factor is qiecified, 1 is 
assumed. 
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After all columns of data have been used, T, X, and <text> format 
phrases in tie fomt stiing continue to be used until one of tlie 
following occurs: 

• an editing phrase (A,E,F,G,0[ T) with a nonzero lep^tion factor 

• the end of the format string 

• a right parenthesis with a repetition factor that has not been fully used 

• aleftiKirenthesis. 

The following example demonstrates how to nest parentheses and how to 
use them to limit scaiming of a format phrase whoi no more data is left to 
be edited. 

ADD *-24pl 2345 678 
ADD*-(*/ADD) .ADD 

•12. < = >. 4(11, (<+>))' UFHT ADD 
10 = 1+2+3+4 
26 = 7*6+7+8 

4-10 Modifiers 

Modifiers add decorations and special effects to edited data. Place \hem 
betweofi the repetition factw and the format phrase. You can use any 
numba of ino^c^ in any ordo'. 

B • Blank 

The B modifier leaves the field blank if the edited value is zero. Use it 
with F, G, and I format phrases. 

EX *■ "65423.43 "10 "0.40 100 

'5F10.1> UFMT EX 
-65423.4 
-10.0 
-0.4 

(0 shows as blank.) 

100.0 



Copyright © 1987 STSC, Inc. 



4-22 



F^matting 



' BG<ZZZZZZ99>' aFHT EX 




■1 ' _ ' 




(0 . 4 shows as blank.) 
(0 shows as blank.) 



€• Comma 



The C modifier inserts commas between each giou|> of three digits in the 
integer part of the edited value. Use it with F and J fijrmat phrases. 

DATA 2987309 3870.23 96874382 38£5 
'CI13' UFMT DATA 
2.987.309 
3 .870 
9J»874.382 
- 3^i-#00 , 000 



. Remember to provide extra positions in the field width for commas. 



^ ' ' The Kmodifia scales (Ini^diesll a number bofoie d^la^g i It 



where i is a positive or negative integer, or zero. A negative value can 
be specked by t tt^09t ^ (Jt '2) m a tttes C)t - 2); 
number to which the K modifier aj^lies is muldplied % 1 0 *i before 
it is formatted. 

'f8.2,Jirif 10.2,;f-2f8.2' OF«T 1 3 p470.6 
470.60 4706.00 4.71 

Use the K modifier with E, F, G, and I phrases. With an F, G, or I 
phrase, the K modifier controls how far the digits are shifted left or 
right of the decimal point in the result. With an E phrase, the K 
modifier adjusts the exponent in the result. 

The following table shows the use of scaling with decimal, 
exponential, and integer editing. 



JT - Scaiing 



IS 
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Format Phrase Number Result 

f6.2 24.60 24.60 

KlFe.2 24.60 246.00 

K-2F6.Z 24.60 0.25 

£■9.4 24.60 2.460£"1 

J!:i£'9.4 24.60 2.460£2 

K'2E9.A 24.60 2.460£-l 

13 24.60 25 

^riI3 24.60 246 

K-2I3 24.60 0 

Scaling is particularly useful when formatting numbers with the 

G phrase. 

Format Hirase Number Result 

G<9.ZZ> 24.60 0.25 

K1G<ZS.ZZ> 24.60 2.46 

J(r2G<ZZ999> 24.60 2460 

KZG<ZZ.99> 24.60 24.60 

K2G<tt.$Z> 24.60 24.6 



L- Left Justify 



The L modifier left-justifies the edited value in the result field. Use it 
with F and J fonnat phrases. 



•119' UFMT 2*1 8 

2 
4 

8 

16 

32 

64 

128 

256 
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When numbers with fixed decimal points or negative signs are 
left-justified, the ali^iment may be unusual. 

'*LFlQ.2f QFUT 34.5 266 0.300 '49.04 

34 . 50 
266.00 
0.30 
"49.04 

If - Negative J^eomtlon 

Tl»Mnm^SBmiefSaEe&tes»!Sm Itlakes 
the ffflm 

M<text> 

where text replaces the negative sign to the left of the result. Use this 
modiflo^ with F. I, and G phrases. Be mm pasM^ to 
fleld width for the decoratkni text lf<~> is the de&ult negative left 
decoration. 

In the following example, the M modifier vq)]aces the AH. negative 
sign (~) by the minus sign (-). 

EX "65423.43 "10 "0.4 0 100 

• ,'Af<->fl0.1' UFMT EX 
-r&S423.4 
-10.0 
-0.4 

0.0 

■ " • ' 100 . 0 

This kind of replacement can be helpful when you use a different type 
font to print a rqport. For example, since ti» APL negative sign ( ~) 
displays as an "at" sign (@) in most fonts, you could use M<-> to 
display negative values with a minus sign (-) in another font. You 

(see "S - Standard Symbol Substitution" in litis section). 
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N - Negative Right Deeora^n 

The H modifio' places text yoa specify to the immediate right of an 
edited neptive value. It tsJces the fonn 

ll<texl> 

where (ext represents the text. Use this modifier with F, I, and G 
phrases. Be sure to provide space in the field width for the decoration 
text 

'iV< MINUS>FZQ .2' DFMT EX 
-65423.43 MINUS 
-10.00 MINUS 
"0.40 MINUS 
0,00 
100.00 

0 - Format Zeros As Text 

The 0 modifia places text you q)ecify in fidds with zero values. It 
takes the form 

0<text> 

v^^mtmmpmms AemL UsetMsnraiiflawii&F, J,trtdf 
phrases. Be suie ID provide spice k the fi<Mwidttif(» the deccffation 
text 

The 0 modifier overrides any f or Q modifier that specifies text or 
decoration for zero values (see "P - Positive Left Decoration" and "Q - 
Positive Right Decoration" in this section). If the text is ^rtor than 
the field width, the text is right-justified in the result. 

'0<NONE> Q< DR> F9 . 2 ' DFJIfr EX 

-65423 . 43 
-10 . 00 
-0.40 
NONE 
100.00 DR 

However, if the L modifier is specified (for F or J phrases only), the 
text is left-justified. If the text is the same length as the field width, 
no justification occurs. 
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• 0<NONE> LQ< M> F9 . 2 • QFMT EX 
"65423.43 
"10.00 
"0.40 
NONE 

100.00 DR 



The P modifier places text you specify to the immediate left of an 
edited positive ok> zoo value. It takes the fqnn 

P<text> 



where text represents the text. Use this modifier with F, I, and G 
phrases. Be sure to provide space in the field width for the decoration 



•P<*>F10.1' UFMT EX 
-65423.4 
-10.0 
"0.4 
+ 0.0 
+100.0 



Q - Positive Right Decoration 



The Q modifier places text you specify to the immediate right of an 
edited positive or zero value. It takes the form: 



Q<text> 



where text represents the text. Use this modifier with F, I, and G phrases. 
Be sure to provide space in the field width for the decoration text. 



'Q< DR>IIQ' UFMT EX 

-65423 
"10 

0 DR 

0 DR 
100 DR 



When H, N, 0, P, and Q modifiers are used with the G format phrase, the 
decoration tdi^'Supersedes text characters in the pattern. The decoration tex 
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appears adjacent to leading or trailing nonzoo digits in the result 
Therefore, the text phrases may not align. 

FMT - 'M<>N< CR>0<NONE>Q< DR>G<Z,ZZZ >' 

FMT QFMT "123 120 242 0 "100 1000 

123 CR 

12 DR- 

242 DR 
HONS 

1 

1 DR — 



R' Background Pm 



The R modifier fills the result field with text you specify in all 
posituMis not filled with the edited value. Ittdtesthefintn 



R<text> 



where text represents the text Starting at the left side of the field, text 
is repeated as many times as necessary to fill the field. Use Uiis 
modifier with A,E,F, I, and G phrases. Be sure to {Hovide space m 
the field width fa the decoration text 



'R<' >ilO' UFMT EX 

• ' "65423 
. . . .-10 

•••0*0 

o e o e o Q 

• • • "100 

' R<BACKGR0UND>I21' UFMT EX 
BACKGROUNDS ACKG-65423 
BACKGROUNDSACKGROU-10 
BACKGROUNDBACKGROUNDO 

BACKGROUNDBACKGROUNDO 
BACKGROUNDBACKGROU 100 



When used with the G format phrase, the R modifier is displayed only 
in positions not occupied by text characters or decorations. 



RDEC 'ff<*>G<$ ZZZ.ZZZ,ZZ9>' 

RDEC UFMT 23987458 38794 287 0 
$ ♦23.987.458 
$ ♦****38,794 
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$ ********287 
$ **********o 

You can use the R modifier to replace leading blanks in the result of 
an A format phrase with nonblank characters. 

'R<->A2' UFMT 3 3p' BOAURNSEQ' 
-B-O-A 
-U-R-N 
-S-E-Q 

However, the R modifier will not put the background text into a data 
position; rather, it win only fiU in leading positions created by usm 
, nq^titiai £actiy. 

'R<*>A2< UFMT 1 8 p'JOHN DOE* 
itJ*0*H*N* *D*0*E 

' Theblankbetwera JOify and I)Of is not filM in widi a backgronad 
star. 

S - StaiulanlSymliol SubsetuHon 

The 5 modifia snbsAotes symbols of your choice for semdard 

symbols used by DFMT. Use the S modifier with F, G, and I 
frnnat phrases. You can also use it with the G format phrase to free 
the-di^ selectors 9 and Z toservefflchan^l^tD%e!n§(»ved^ die 
result, and with an F or J format phrase to tailor other formatting 
effects to individual needs. S allows only a one-to-one substitution of 
'symbds. 

The 5 modifier takes the form: 
S<s]^nbolpairs> 

whaie die first ^mbol in eadi pair ni^ be on&of file ^mbols in the 
following table, and the second symbol is the tempcxary lepk^ement 

for the first 

_ , This table contains a list of symbols that can be replaced using the S 
modifier. Applicable format phrases are shown in parentheses. 



Copyri#ii^€>'i987 STSC. he. 



4-29 



Fonnatting 



Symbol Purpose (Applicable Format Phrases) 

9 Digit selector (G) 

Z Digit selector, with leading and trailing zero suppression (G) 

* Field ovoflow fill character (f , JF, G, I) 

Decimal point (f) 

. C modifiv insQt characta (F, I) 

0 Z ms)&3^Mehamsm (F, I) or teadmg-zm) fill character 
fiom a 9 di^t selector (G) 

The following i^ample shows how yoii can use the 5 modifier to 
. display decimal numbers as clock times. 

10:00 10:15 10:30 10:45 

Hiil^bstitution affects only the format phrase with the S modifier, a& 
in die next example. 

•S<.V>F5.1, f9,3' nPMT 1 2 p470.6 370.168 
470V6 370.168 

You can substitute for more than one symbol in a single format 
phrase. For example, symbol substitution can be used to follow 
European COnVi^liQiis, where periods rather than commas are used as 
number separators, and commas rather than periods are used as decimal 
points to mark the Iraciional part of a value. 

'S<. . . .>Cfl4.2' UFMT 1234567.89 
1.234.567.89 

The only substitutions permitted for symbols in the left argument to 
UFMT are those for the digit selectors 9 and Z in the G formal 
phrase. The other substitutions that are permitted affect symbols that 
UFMT places in the result In the next example, the 5 modifier frees 
the digit selector 9 for use as a character in text. 
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'S<9_>G<19__>' UFHT 64 57 72 54 

1964 
1957 
1972 
1954 

Use the 5 modifier to iqiiace the stars that mark field overflow. 

il «- o l£2 1 
'F5.2' UFMT A 

* * * * * 
3. 14 

•S<*$>f5.2' OFMT A 

3:14 



The following uses of standard symbol substitutUMi produce a 
FORMAT ERROR: 



• An odd number of symbols appears between the delimiters; for 
<sp^pie, S< . >. 

• The first symbol in a pair of symbols is not in the preceding table; 
for example. S<V. >. 

• More than one substitution is made fior the same symbol in the 
samefoimatpluas^ fin' example, S< . : . , >. 

• - ~ . The same symbol is substituted for the digit selectors 9 and Z; for 
^ ' '"'fe&fii^, S< 9_Z_>. 

Z - Zero FUl 

The Z modifier fills unused leading positions in the result field with 
zeros instead of blanks. Use the Z modifier with land F format 
pjtirases. 
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' ZIIO ' QFMT S)*! 2 3 4 5 
0000000003 
§000000006 
0000000003 
0000000012 
0000000015 

The Z modifier can also be used to display telephom numbers whoi 
exchanges and trunk numbos have been stored separately. 

EXCHANGES - 355 298 385 448 
NUMBERS - 56 7980 230 66 

'I3.<->.ZI4' aFMT EXCHANGES NUMBERS 
355-0056 
298-7980 
385-0230 
448-0066 

When the Z modifier is used with an editing phrase to format a 
negative value, the negative sign is left-justified in the result field. 

•ZI5' UFMT -10 1 

"0001 
00000 
00001 



4-11 Combinations of Modifiers 

When the B modifier and 0, P, or Q modifiers are used togeiher, any 
data values that are zero appear as blanks, and the decoration text does 
not appear in the result field. 

' B0<N0NE>I5' UFMT "1 0 1 

-1 
1 

•BP<+ >I5' UFMT -10 1 

-1 
+ 1 

When the J and S modifiers are used t^^ier^ my values that are 
zero do not suppress the R fill text in the result field. 
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'SR< N0NE>F5.2' UFMT "10 1 

-1 . 00 
NONE 
l.QQ 

When the 5 and Z modifiers are used togetha:, any data values that are 
jviiisiq TO A jg-t .r3i^;<5y( fyvr- 'ji- / i .t w , ■ 'i ' ' zero appear as blanks in the result field. 

•JZI5' OFAfT -1 0 1 

-QOOl 
00001 



When the L and 0 modifiers are used together, text specified by the 0 
modifier is left-justified. 



5 - II 



..!;■••< »vm (»jaf.vi:,«^ 'LO<NONE>IA> QFMT "10 1 

,...1,1, ,^ ;, V V 'i-i f, 1, "1 

NONE 
I 

When the L and Z modifiers are used together, the Z modifier has no 



'LZI5' DFAfr "10 1 

-1 

1 

' - =<w, : ; ' , ;• . •,•;. '!.( ,,";; When the Af and Z modifiers are used together, each negative data vtdos 

— . t-' i-ri 1 1- appears with its negative sign replaced by the A/ decoration text The 

decoration text is left-justified in the result field. 

•Af<- >ZZ5' DfJIfr -101 

- - - i ■ i.f • J f " • - 001 

00000 
00001 

When the 0 modifier and the P or Q modifier are used together 
' - ' . •; without the B modifier, any data values that are zero are formatted by 

^ 0 text rather than the P or Q text 

tVv . "■br - r'' . c b '■■ '■< ; 
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<0< 7>P<t>Q<l>Li5* QFMT 0 12 3 

V 

[1] 
[2] 
[3] 



When the P and Z modifiers are used together, each zero or positive 
data value appears with the P decoration text and is left-justified in the 
lesuU field. 



'P<+ >ZT5' nPMT -10 1 

-QOOl 
+ 000 
+ 001 



When die R modifier is used with one or more M, N, 0, P, or Q 

modifiers, the decoration text overrides the background text for the 
portion of the field covered by the W, //, 0, P, or Q modifier. 



FS-<-'R<*>M<->N<->Q<HONE>P<*>Q<*>IS* 
FS UFMT -10 1 

*NONE 
** + ! + 



4-12 Useful Applicatiom 

Here are some examples ctf commercial applications that use UFMT with 
combinations of modifiers. The nomesic anay WH is used in most of the 
examples. 

NUM 

1316026.715 765715.3407 4587093.116 

11586.9 2190044.457 "471009.5613 

6789137.817 0 9347189.744 

3836077.871 -S195105.458 234.5 

Float Dollar Signs and Place Negative Values in Parentheses 



<C P<$> Q< > M<($> N<)> F19.2' OFMT HUM 
$1,316,026.72 $755,175.34 $4,587,093.12 

$11,586.90 $2,190,044.46 ($471,009.56) 
$6,789,137.82 $0.00 $9,347,189.74 

$3,836,077.87 ($5,195,105.46) $234.50 
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Format Negative Valm^ into Separate Columns and 
Omit Negative Signs 



\H*im*,.- > CI AO' 



471.010 



5.195,105 

Display Decoratiota Only 

BOOLEAN -^00101 
'P<YES>R<NO >BI4. Jf-1, < >• UFMT BOOLEAN 

NO 

NO 

YES 

NO 

YES 

4-13 Stars or Unknown Digits in Result 
Stars in Result 

If stars appear in your Whm ;^ti M not expect them, you probably 
ii^P^J|fr inconectly. Stars q>pear in the result when: 

• A formatted value is larger than die field width (often because you 
forgot to account for the width of decorati(»s in the field width). 

• You tried to use an i4 format phrase to edit numeric data. 

' ;r ' . ' V You ttied to use a format phrase other than A edit character data. 
You can avoid these conditions by using a larger field width, by 



UFMT . NUM 
1,316,027 
755,715 
4,587,093 
11 ,587 
2, 190,044 

6,789, 138 
0 

9,347.190 
3.8|g«078 

235 



scaling the data, or by using the correct format phrase for the datatype. 
You can always substitute another symbol for die star by using the 5 
modifi^' (see Section 4-10). 

Unknown Digits in Resuit 

The precision of the result of UFMT is independent of the value of 
nPP. DFMT displays up to 17 digits. A format phrase rtS^uestfng 
more significant digits than are available in the int^nal rqnresentation 
uses zeros for the missing digits. 

•F24.1' QFMT oi£20 
314i5926S358979330000.0 



4-14 Workspace FORMAT Overview 

The workspace FORMAT supplied with your APL* PLUS System 
contains sevoal functions tfiat wiD Help you pla^ ^&e» iUidiow and 
column names on a rqxnt These functions ^ into die following 

categories: 

• Title functions allow you to position titles over your report. 

• Label functions allow you to label rows or columns of your report. 

• A special fiinction aUows you to build custom titling routines. 

Use these functions in conjunction with QFMT to help you generate 
yomnpsM. teead df loading the aidcewfokq^, youcan cqpy 
any of these futons into your workspace with the command 

) COPY lAPL . RELnl FORMAT objects 

where objects is a list of one or more desired functions. 
Title Functions 

Each of the following tiding functions produces a character mauix as 
an explicit result The matrix has the same width as the result of 
DFMT used with the same format string, which permits catenation of 
titles (Kilo fixmatied data to form laigar ch^uacter matrices. 
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CENTER Center a title over a report. 

LJUST Left justifie a title over a report. 

MUST Right justifie a tide ovCT a iq)oit. 

Label Functions 

The following functions set up labels for rows and columns of a 

report. 

COLNAMES Label columns of a report. 

ROy NAMES Label rows of a report. 

v^-iiiii.-. ijaiH>. Ml: Custom Titling Routines 



Hie CENTER, LJUST, RJUST, and COLNAMES funcUons 
analyze a format string using the £1/12) function. You can use 
WTi) directly to design you own tidnag lODtioes to mecx y^ needs. 

Using the Functions in Formatting Programs 

t w * 

The following program GO uses functions in FORMAT in 
conjunction with DFMT. 

V CO Diiri4:FSr»;JI|ir 

CI] FSTR->-'BAl. X2, IS. F10.2. F1S.Z> 

[2] Je/^«-8 ROVNAMES < /NUTS/BOLTS/SCSEVS' 

131 FSTR CENTER 'INVOICE' 

[4] FSTR COLNAMES < 'MATERIAL'QTY'COST'EXTENSION' 

LSI FSTR QFMT (.RN-.DATA) 

■j.iv run • •-. I , = 

yp^r. ! :u. : ■rWi'O "^3 3 p20 0.15 3 9 0.71 6.39 3 0.42 1.26 

6d INFO 

INVOICE 

•?yA .1, :v - -sA. MATERIAL QTY COST EXTENSION 

NUTS 20 0.15 3.00 



ri,r 



BOLTS 9 0.71 6.39 

SCREWS 3 0.42 1.26 
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To speed up execution of your rqmits. use the following two 
tediniques: 

• Separate report setup firom report pcxfaiction. 

• Avoid repeated analysis of the same format string by the RVTD 
function. 

Separating Report Setup from Report Production 

To save execution time when producing reports, use a separate "setup" 
program to prepare and store as variables portions of the report that do 
not change, such as titles and row and column labels. The repom 
program runs faster since it is only printing the saved variables rather 
than computing them. Using this approach, the function GO (shown 
ineviously) is replaced by two fimcticms SETUP and REPORT. 

V SETUP 

111 FSTR^' SAl ,XZ,I5,F10 .2,F15.Z' 

[2] RN-^S ROUNAMES ' NUTS/ BOLTS/ SCREWS ' 

[3] TITLE-FSTR CENTER 'INVOICE' 

[4] COLN*-FSTR COLNAMES ' •MATERIAL'QTY'COST-EXTENSI 
V 

V REPORT DATA 
111 "0 TITLE « • • 
[2] COLN 

C3] FSTR DFHT <.RN;DATA) 

V 

The SETUP function places four global variables in the wwkspace, 
to be used by the REPORT function. The REPORT function can be 

run as many times as needed once SETUP has been run. If the report 
specificauons change, revise SETUP, run it once, and save Uie 
workspace for fliture use. 

Avoiding Repeated Analysis by the RWTD Function 

When a format string is given as the left argument to LJUST, 
RJUST, CENTER, or COLNAMES, these functions use RWTD to 
analyze the fisrmat before proceeding. However, if the left atgfunent to 
these functions is numeric data, the functions assume it is the proper 
result of an earlier analysis by RVTD and bypass the use of RVTD. 
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HiordTare, to save execution time use one of the ^tt@^;<^ng procedures: 



• Clill SVTD separately and save its result for use as the left 
toffmemio LMW* MM$fi fiJ91*Si, m^QtSMiM, 
Lines [ 3 ] and C 4 j of SETUP in the pie<4oi£$ mmple would 
run faster as: 

[3] RR-^SWTD FSTR 0 TITLE*-M CENTER 'INVOICE' 

[43 COLN^RR COLNAMES ' 'MATERIAL'QYT'C&Sf 'SmtKMtm^ 

• Use a numeric vector of field widths instead of RWTD. The 
COLHAHMS pmgim will ri^t justify headings over Mds wilA 
positive widths, and left justify headings over fields with negative 
widths. Lines [ 3 ] and [ 4 ] of the previous example would then be: 

[3] RR^-B 7 10-15 0 TITLE^RR CENTER 'INVOICE' 

[4] COLN-RR COLNAMES' 'MATERIALoQYT* COST 'EXTENSION' 
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In addition to numpoMi^ fiie screen ftm the tomritaal k&yb^ad, the 
APL* PLUS System provides system functions to manipulate the 
, scxegn under program control. Using these facilities changes the image 

a :>.' i><. ii ; of dieAH^ sessi(m screen in memory and also causes APL to transinit 

the necessary coniiDl sequences to tramuial 10 produce 
effect. 

5-i Simple Input and Output Management FadMes 

The building blocks of simple input and output facilities are the □ 
(quad) for liuffl^ data and 13 (quote-quad) for character dataL The □ 
can be used in an expression like n--A to display the contents of A at 
the luminal. It can be used in the expression A--Q to wait for input 
firom the tominal and store it in the variable A. The □ works the 
same way for character input, except that on ouQMit (□♦■4) it does not 
display a carriage return at the end of the data. 

A typical function might use □ or □ both to accept input data for 
processing and to display the result of the operation: 

^UPDATE 
[1] n*-' ENTER NAME: • 

[2] NAME^?} 

[3] a*-'OK. '.NAME.' HOW OLD ARE YOUl ' 



V 

The function above would begin execution as follows, with user input 
in bold: 

•'l^ ■« . " , ■■■ 



:l; ^nj -'.I'-. 



UPDATE 
ENTER NAME: 
SHITB 

OK. SMITH, HOW OLD ARE YOUl 34 



In the UPDATE function above, AGE will include leading spaces to 
indicate the location of the entry on the line. Some older APL 
systems return the entire line (including prompt) rather than spaces. If 
you have programs that require this behavior, you can set OPS to ' ' 
to emulate the older style. See Chapter 3 of the APL *PLUS System 
Reference Manual for details on UPR, 

Other APL* PLUS systems use the expression: 

n-^' PROMPT' 0 UARBOUT lO 0 ANSWER-^n 

to diminate anything on the fine eicqH die us^'soitiy. The 
AEL^PLUS Syston fsx VAX/VMS supfKHts this idiom. 

OARBOUT lO is a special definition of □i4/?J?0[AT. Normally 

UARBOUT can be used to send any ASCII character to the screen. It 
sends arbitrary character data to the screen, interpreting the numeric 
codes gfven m ie argumem as the conespoiding ASCII character. 



Several system constants are provided to simplify sending control 
characters to the terminal. They can be used to produce special actions 
on die terminaL The system constants take the form UTCnn and 
pixxluce the following conttd charactm: 



Terminal Control Characters 



Bell: 

Backspace: 

Delete; 

Escape: 

Form Feed: 

Linefeed: 

New Line: 

NuU: 



nTCBEL 

UTCBS 

UTCDEL 

UTCESC 

DTCFF 

OTCLF 

DTCNL 

niCNUL 
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Note how some of these are used in the example below. For details on 
the terminal control system constants, see Chapter 3 of the 
^0*t*FtjVSSymmIt^^nce Manual. 

' ' In conjunction with □ and □ on output, UCURSOR cm position the 
output anywhete on tiie screen; D7CFF can be used to clear the screen 
altogether. The session-related variable OC[//?SOi? contains the 
current location of the cursor within the current window on the screen. 
Its value is a vector coitaining the row and column of the current 
cursor position relative to the uppet left comer of the window in use 
{seeUWINDOV). 

You can assign UCURSORa. new value, which will immediately 
cause the cursor to move to a new location. The following function, a 
slightly enhanced update program, clears the screen and positions (he 
question oa the screen: 

V UPDATE! 
[1] UTCFF 
[2] UCURSOR - 4 15 

[3] a-' ENTER NAME: ' 0 UARBOUT lO 
[4] NAME^a 

[5] REPLY-'OK, '.NAME.'HOV OLD ARE YOUl 

[6] UCURSOR - 6 10 

[73 a'^REPLY.QTCBEL 0 UARBOUT iQ 

y 

If you have a large quantity of text to display on the screen or if you 
want to specify display attributes such as reverse video, OWPUT is a 
; , useful tool. This system function replaces the characters or attributes 

(or both) in a specified screen window. UVPUT has the syntax: 

' v^cUVPUTdata 

where wspec is the optional specification of a window other than the 
".A-<ii\' ' current one, doAdata is the data to display in the window. The wspec 
lio ih argument lakes tte fixm of the sessicm-related variable VMIKLQM, 

WINDOW is a vect(»r whose first two elements are the absolute 
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screen position of the upper-left comer of the window and whose last 
two elements are the shiape of the window. 

The system function that corresponds to UVPUT on input is 
nVGET. UVGET reads the characters or attiibates (or both) ftom a 
specified screen window. It has the syntax: 

result *■ w^c UWGET rtype 

■ndiere yifspec is iSat (piomd qpecificatioa of & wuidow (Mhgr itm ihe 
currrat one and rtype is die ^pe of result desired: an integer code firom 
1 to 4. 

I^lay Attribtttes 

Most CRT terminals provide a &cility for dsplay attribuG^, altowiiig 

the display of characters to be emphasized by reverse video, high 
intensity, or blinking. The APL*PLUS System allows you to 
mariipiHate the ^spUiyaia^btttes on the screen usmg UMGET and 
UMPUT. APL uses a logical attribute approach to standardize the 
handling of atuibutes on a wide variety of terminals. 

The logical attribute is a number representing the combination of 
attributes that are used to display a character. Each possible atuibuie has 
a numeric value, and the combination of attributes is expressed as the 
sum of these numbers. This APL* PLUS System is capable of handling 
up to 8 distinct display attributes in 256 different combinations. Most 
monochrome terminals support 4 attributes. By convention, the 
attribute are identified to APL by the following attribute values: 

0 default display torn for die tenninal 

1 reverse video 

2 alternate intensity (brighter or dimmer than usual) 
4 blinking 

8 underlined 

For ©cample, to make a 1 0-by-lO section of the screen di^Iay in 
reverse video with blinking characters, use: 

0 0 10 10 UVPUT 5 
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3h^i(KtrilMte coRv^tkms «^ only if ^ti^ 

used contains the necessary definitions. See Appendix D for 

inclination on the structure of the termcap database. 

To ci^ture a single keystroke^ use ^ 83«iem fiuK^m 
Where D captures all input until the user presses R^Uin, UINKEY 
_ . 1 .' . ' takes only a single input character. For example: 

. -l,SiS:^^£M^MtMy TO CONTINUE' 0 KEYSTROKE-QINKEY 

_i DJ/Z^f yaUows you lo write AFLfffogiams that lou^t to eKh keystroke 

i the user types it 

VdngAeProgrammaUe Function Keys 

The AFL*FLUS Syston includes a £acility iat d^idng a#oiq) ctf 

logical programmable function keys that provide a faster method to 
type pre-defined sequences of keystrokes as input. This facility is 
. i^ependent of any real function keys that you may have on your 
terminal keyboard, and you can use this facility even if there are no 
function keys on the terminal. 

A function key is used by typing the PF-key keystroke (also known m 
the Alt-Key) followed by any other single character. A distinct 
fimction key is defined for each of the 128 ASCII characters. For 
.^cample, suppose that the function key value for the " 1 " key is defined 
to be the six-character sequence C WARS* ,U TCNL). Then, whwi 
you press PF-key followed by 1 , a )VARS and a simulated Return 
I , are di^layed as though you had entered them yourself from the 
keyboard. 

Each function key has a default definition. The most commonly used 
iyRbovoRBfleesean aUbeproda^ 

These keys have been chosen to correspond to the way the Alt-shift 
key is used to produce overstrikes on the APL * PLUS System and on 
EBM 327()-seri6S tKininals. Thus, PF-key followed by ^ , " pn>iaC68 
n , and PF-key A produces a . this reason the PF-key keystroke is 
also known as Alt-key. 
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The diagram belows shows the default definitions that coacspond to 

the Alt-keys on other keyboards. For the other ASCII charact^, the 
default function key yields the character itself. 



q 


w 


e 


r 


t 


y 


u 


i 


0 


P 


□ 





Ctrl Lock asdfghjkl** A 



Shift 



Shift 



A single function key sequence can be defined to have as many as 64 
I^Biactas, but the total for all 128 function keys cannot exceed 5 12 
diaractos. 

The system fanction OPFiTf 7 reports and optionaUy modifies the 
definitions of the function keys. Used mcHiadically, it rqmts the 
current definition: 

UPFKEY •!• 



Used dyidicaUy, it dianges the definitioa: 

< ' )VARS' .^TCHL ) UPFKEY '1' 

The effect of the above statement is lo make PF-key 1 expand into the 
omunand )VAfiS. Note that aPFArfy makes die distinction 
between shifted and unshifted keys. This makes it possible to assign 
key definitions that, when the text keyboard option is in use, are the 
sanwas die "unified" teyboard used by the APL*PLUS PC System. 

UP F KEY is described in detail in Chapter 3 of the APL *PLUS 
System Reference Manual. 



Copyright © 1987 STSC, Ine. 



5-6 



Screen and Keyboard Management 



Character to Numeric Conversion 



Frequently, data captured from screen input must be converted from 
character to numeric. The system function DFI will convert character 
'.Urucc' ■.jK::^f, - vectorsttai are images afnombos to their numoic form. Its synt^ 

result - DFI dioia 

' '. where ^/a is character data. The result is a numeric vector formed by 

laiing successive gnxqis of nonMank ebaiaeiefs fiom the aigameoft^ 
' • ' • ^ ' .1 convoting them to numbers. Any characters that do not represent a 

'- — weU-foimed number appear as zero in the result. For example: 

DFI 'MSVER: 666' 

0 666 

Other algorithms using the execute primitive ( £ ) could be used for 
the saine puipose bw A (lodace »i emt ii^sage 
incoQII^ fijimed data, ladiar dian imniing a z^. 

<'.': .f : > r . syston funidofl Oy 

a / • ■ , . . u i;;!, provide a validity check on the input character vector. The syntax for 

UVI is the same as for Of I but the result is a Boolean vector with a 
,,M.< 1 ineaGtapraitiondiatii^ieseniiaw«ffi4gimedwimb@^^^ 

each group of x^aractHS ttat does not toaa a v^d namb^. For 
example: 

QVI 'ANSVER: 666' 

or 

AnoSia' idiom conmionly used to convert only valid character input 
into numeric iiqmt is: 

. . ANSWER*-a 

^ ' NUMANSVER'-invI ANSWER) /UFI ANSVER 

Hea» is ainlfaer exanqde (tf character omv^ 

C«-« .25 -6.25 8.9.10' 
DFI C 
0.25 0 0 



avi c 

10 0 

As suggested by the last example, a minus sign (-) cannot be used in 
place of a negative sign ( ~) to negate a number; and commas and other 
symbds do not serve to stpuate fields. An example of a tedinique for 
modifying sadi symlxds to fonn a valid argimient for □ FX is: 

EXT^' 0123456789£'. .+-' 
INT^' 0123456789£. " ' 
DPI INTiEXT\< .25 -6.25 8. 9. 10'] 
0.25 "6.25 8 9 10 

For more detailed information on the use of each of these system 
functions and constants, see the APL *PLUS System Reference 
Manual. 

S-2 The INPUT Workspace 

The APL* PLUS System includes the workspace INPUT that 
con^ns utility functions incorporating the system functions described 
above. The utility functions are easy to use, have widely accepted 
default behavior, and can handle special requirements as well. The 
functicnas include the following bdlt-in features: 

• same-'line prompting 

• help messages 

• nonnalizati(Hi of input 

• checks and limits on input length 

• oior messages 

• keyword detection (such as HELP or END) 

• customized ivocessing. 

The input workspace contains fuctions that accept and manipulate 
input Six input functions whose names begin wiiA IP fc»m the core 
of the workspace: 
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• IPCHR accq>tschafact» input 
- « LPHUM xcepts numeric input 

• IPMATCH accepts forced choice input (character ornumeric). 

• IPMIX accepts combined characttf, numeric, and forced choice input 
' IJiBULK aaseptshf&inpoL 

» IPYN accepts variations of "yes" or "no" and calls f PHIX. 

These functions can be used eithet as stand-alone functions or as 
' fonetienS'dBttcaH the input primitive IP. All six functions pnmipt 

for and accept input, remove superfluous blanks, check input length, 
display more detailed prompts on empty input, and reprompt if 
fidiesitt^.'wMi mor me^^. tiiei^ff^nal globd i peso is 
defined, the functions detect keywords like HELP, END, or QUIT and 
return a distinguished result if a keyword is encountered. You can also 
compose qnsiomized iiqwt functions uang these Sanctions as buil^ 
blocks: 

• DEB deletes excess Idanks (leading, trailing, and consecutive). 

• DLB deletes leading blanks. 

• DTB deletes trailing blanks. 

.1 * - 

• SSDEB deletes excess blanks fixm substrings of a segmented vector. 

• SSMATCH matches data against a segmented vectcr oFkeyw(»ds. 

• SSGLB converts a segmented vector into a set of global variables. 

• SSMAT converts a segmented vectcv into a matrix. 

• SSVEC converts a se^nenfed vector kito an aligned vector. 

The input workspace also serves as a source for these commonly used 
input fimctions: 



• AKI accepts keyboard input. 

• WXP accepts numeric input. 

• AYN accepts "yes" or "no" responses. 

Broader capabilities, however, are provided by the functions IP CUR, 
IPNUM,aRdIPYN. 

To most effectively use the input workspace, you need to answer some 
basic questions about your data input requiiemoits. 

What Kind of Input Are You Requesting? 

Are you asking for numbers, such as salary information, or are you 
requesting character data, such as an employee's name? Do you want 
to r^trict input to spedEc dK»ces, as in: 

CHOOSE ONE OF: ADD, CHANGE, DELETE 

Do you need to request input of mixed datatype;, such as name, age, 
and alary? Do you need to coltect sev&si limes of input at once? 

If you want this kind of input Use this function 

numeric IPNUM 

character IPCHR 

^ified choices (numoic or characta) IPMATCH 

mixed (numeric or characta) IPMIX 

bulk input IP BULK 

How D9 f0U S§t Up a frompi! 

Hhe lij^t mgwnent to each input fimettion is a vector of one or more 

prompts. The leading prompt should be brief since it is displayed each 
time input is requested. Subsequent pompts should be detailed 
raoogh to clarify tli& leading ;^ompt They are displayed wfa^ a user 
requests help by pressing the Return key when prompted for input 

If you need to request phone numbers, a possible line of code is: 

h^l IPNUM '\PHONE: 13 NUMBERS (E.G. 301 657 1872) 
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An experienced user would gaierally need td see only the first {xompt: 

PHONE: 301 320 4089 

But if the user needs help, he can press Return to request more details: 

PHONE: (Return) 

3 NUMBERS (.E.G. 301 657 1872) 
PHONE: 301 320 4089 

How Do You Restrict Input? 

"Be M aqpiment contains control information. 

IPNUMmAIPCHR 

Do you want to restrict the input length? Can input be of any length? 
Mast your iipit fit in a image of teigihs, such as 1 to 30 cfa^ters? Or 
do you need exactly two numbers? 

Length r^trictions? Yonr left argument shonU lie 

.No lO 

. ..Yi^, exact lengths one more non-negative integers, sirch as 

2 4 for two or four characters or numbers 



Yes,, a rangS: of lengths one or two non-positive integers such as 

"3 for one, two or three characters or 

numbers, or "2 ~4 for two, three, 
or four characters or numbers 

If you wantio request exactly three numbers, you can use ^s statement: 

3 IPNUM n PHONE: \ ENTER 3 NUMBERS' 

If you need to store employee names with a maximum length of 40 
'C3wmiebas;^m can use die foQomng input statement: 

-40 IPCHR '[NAME: \LASTNAME , FIRST MI' 

toiuc^tresponses containing 1 to 40 charactos. 

^ r . 1 ■. . 5-11 Sciven 1 



IPMATCH 



IPMIX 



What kind of choices do yoa teqtnre? Ai^ your choices numoic (for 
oiample, a valid zone number of 1 , 2, or 3) or character? If character, 
are you accepting exact matches only {ADD exactly matches ADD), or 
am)^iakiagparMflatches as «^ (A, AB, and ADD match 
ADD)1 Are you taking only "yes" or "no" responses? 

If your ch<rices are Your left argument should be 

numeric a numeric vector 

chaiactff, partial matches a s^mented string of choices 

(LA*- ' I SINGLE I MARRIED ' ) 

duuaeter, exact matches a segmented string reshs^ied into a 

one-row matrix 

(LA- 1 1 5 p • I SINGLE I MARRIED ' ) 

"Yes" or "no" LA*- ' I YES I NO • 

You can also use the unlocked cover function IP YN if you v/mt only 
"yes" or "no" respcmses. IPYN\mi built-in left argun^t of 
\YES\NO and renrnis a Boolean resuU. 

The resdt of IPMATCH a m^lenmt integer veiitc^ sadicating 
die number of the matched segment* 

S*-' \§IIfGLE\ MARRIED' IPMATCH 'MARITAL STATUS: ' 
MARITAL STATUS: M 
R 0 pp* 

2 
1 



What combination of data do you require? Once you have determined 
«^ typ^ of data you want, you need to decide what length 
restrictions (as for IPCHR and IPNUM) and specific input choices 
(as for IPMATCH) you need. Each field of input rcquucs a control 
specification. For example, if you are requesting a name and age, you 
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can ^edfy two control specifications in the left ars^ngnt: 

-402 13 IPMIX ^ /NAME /AGE: • 

The integer "402 specifies character data (type 2) of length 1 to 40; 
the integer 1 3 specifies integer data (type 3) of length exactly 1. 

Do You Want to Detect Keywords Like HELP or END? 

If so, you must create a global variable called i pe SC. It is a 
segmented string of keywords, for example: 

ipesc-* I HELP \ END' 

and it is defined in die same miy aa die aigiiin«it to IPMATCH 

with regard to exact and partial matches. A match to i pesc is 
returned as a scalar integer to distinguish it from other data which is 
always returned as a vector. titet On some hardware, lowercase 
APL charactos (i pe s c) may afipear as underscored APL characters 
(IPESC) . 

Do You Have Special Processmg Needs? 

The input functions perform quote-quad (□) input and output, 

including the display of enor messages. If you have special terminal 

ie(iabein@ats, you can wsilB a noQ-^eMt r? fiw^imlD 

For examj^ you can have IP dear die screen befoe a nsor raters 

input 
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Computers often need to exchange information with other computers 

peripheral devices. The primary feature of the APL*PLUS System 
enabling such communication is the system function UARBIN, 
□ili2£ri\^ can be used to create print files (see Chi^ta 8) to gather 
in&mation from the keyboard (see Chapter S). 

This chapter will suiv^ the use of U ARB IN and then review the 
q^lication built with UARMIN, SERHOST (Section 6-3), to move 
AFL workspaces and files fiom one APL System to another. 

The other way to commuoi^e^ between APL Systems is to move an 
^i^i^'woclcspace ffle t& a Mtive fite \(dA the io^^ 

SLT or TRANSFER workspaces. A file transfer j^pHttl as 
Kermit can move the file from one machine to the oth^t 

The SLT woricspace is discussed in Section 6-5. Ways to move flies 
from machine to machine are discussed in Section 6-6. 

• - ■■a^- - 

6-1 Bow to Commurdea^ iivi^ Remote Dmiees 

Hie system fimction [\ARBIN provides a facility for detailed control 
of input and output between APL on the VAX and the user's terminal. 
If the user's terminal is actually another computer, such as a PC 
xonniAg the APL*PLUS System, UARBIN can be used as the basis 
' ifttetom^Btring iaala bm^een flie two ecaapnBars under program control 
The SERHOST worl^Kice is an ^tample of this kind of data transfer. 

- WS'sytmtitkniAR^SINis: 

result *- paramlist UARB IN prompt 

where result contains any received data, paramlist is a list of 
parameters that describes where and how to communicate, and prompt 
^is^ data to be transmitted. 
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The left afguniKit is a vector (of singtefisn) of iiiteg^ desfirtbing how 
the communication is to be carried out. If the left argument is a 
singleton, it specifies the oulport and awaits no input, but 
immediately tesumes kical {Hocessiig. If inpitt is expeeted, or if you 
are specifying values other than default values, the left argument 
contains the following elements in this order: 

[1] oulpoit— destination of data 

C 2 ] inpon — source from which data is to be received 

[ 3 ] translation — translation table to be used 

[4] protocol — transmissicKi protocol to be used 

C5] wait — number of seconds to wait for data 

C 6 ] chailimit — maximum number of characters of data 

[7] terminators — list of tomination codes. 

The elements are used starting from the left; if fewer than six elements 
are given, the remaining parameters assume the default values. For 
detailed infmnation m synm, de&ruU vaines, mA behavior of 
U ARB IN, sec Ch^t£7 3 of the APL *PLUS System R^erence 
Manual. 

The first two elements of the parameter list iztiUARBIN where to 
send data and from where to receive it These are described as the 
outpcfft, or the destination of data you are soiding, and the inport, 
or the source of data sent to you. The other pvameters are used to 
conUDl how these ports are handled. 

6-2 Transferring Data from Other APL Systems 

The APL*PLUS System contains several utility workspaces and 
programs to help exchange workspaces and files with APL Systems on 
oiher oomputm: 

• SERHOST - a workspace for uansferring APL component files 
between the APL*PLUS System for VAX/VMS and the 
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APL*PLUS Systems ftwtfie PC or Macintosh. SERHOSTeaa 

be used to move workspaces as well as files since workspaces can 
be stored in APL component files and later recreated into 
woikspaces. 

• TRANSFER ~ is in a workspace containing a number of useful 
utilities thit etn 1)6 nsed M mojamiim widi Kamit mma&isx file 

''Mmsfor technique 

• SLT-Sduieel^elTiass^-isBworiQpacewiAiiinc 

will transfer wodcspaces frcwn one APL system to maOia using 

the Workspace Interchange Standard. 

The kind of data being transferred and the degree of compatibility 
between the source and destination systems determines which tools are 
' iiidst^>pn>p(iaiBtouse. There ^ several (Meiait kinds of 



• APL wodcspace and component file compaubility - - A workspace 
saved on die APL*PLUS PC ca UNIX system cannot be loaded by 

f^l^¥tfL»PLUS Sysim for VAX/VMS. TMs is trae even between 
the VMS and ULTRK versions of APL for the VAX. The internal 
structures of saved workspaces and component files are different for 
each An.*H.U$ Systm inq>I»n«itation. 

• Character set compatibility - - The order of characters in UAV for 
Oe AfL«]>LUS System for VAX/^t^ is exacdy the sMie ts ttte 

APL ♦PLUS PC System, but differs from the APL ♦PLUS UNX 
and APL ♦ PLUS Mainframe systems. APL character data must be 
translated when moved to sysions with ^et&a UAV ardw. The 

SERHOST workspace handles UAV differences automatically. 
Explicit translation is needed, however, if you use a native file-based 
u-ansfer between the APL ♦PLUS System for WAX/WMS and 
APL*PLUS System for UNIX. The TRANSFER workqace 
contains functions to perform this translation. 

• APL source level compatibility - - APL programs that look the 
same prodoce die same effect. The APL *PLUS PC, Mac, UNIX, 
VM, MVS, and VAX/VMS systems are source level compatible at 
the APL standard level and the APL* PLUS standard level with only 
a few excqptiois. Nested arrays are not available on the MiK^intosh 




m ^jmmmpM. ths AfMfWJS Syst^s for 'VhWVMS mi 
for UMX are completely compatible at die source level. 

The APL standard level consists of tte AFL i^imitves, sj^tem 
functions, and system variables that are defined by the ISO/ ANSI 
standard for the APL Programming Language. The APL* PLUS 
standard level is a sup^set of tti& blie All.^filidjtfd, cfflitaining die 
STSC enhancements to APL whose behavior is compatible across 
all versions of the APL* PLUS System. Any system feature that is 
not identified as "system dependent" or "expajmoital" can be 
assumed to be an APL*PLUS standard. 

It is be practical to transfer APL programs and data in source form 
between the various APL* PLUS systems. Conversion is likely to 
be required only where "system dependent" or "experimental" features 
aieused. 

The APL*PLUS Systems for PC, UNIX, and VAXA^MS Systems 
are partially compatible in certain system-dependent device control 
features such as UARBIN, UVGET, DVPUT, and DINKEY, 
which are as similar in the three environments as is technically 
practical. In many cases, it is possible to move code that uses these 
features between the systems with very little conversion. 

6-3 Using the SESHOSTand SERXFER Workspaces 

The easiest way to move APL functions and variables between either 
the PC or Mac systems and the VAXA'MS System is with the 
SERHOST w(^tspace. For addi^cmal inf(mn^n on SERXFER 
see the APL ♦ PLUS PC Programmer's Matmal, or the APL*PLUS 
Mac System documentation. 

Tim PC or MacintO^ must use the terminal mode of the APL * PLUS 
System to sign (Xi to die VAX in order to use the SERHOST and 
SERXFER woHcspaces. 
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Summary of FefiiailliA Computer to VMS Tranter VstUgSERXFER 

1 . If tiansfening workspaces, create a transfer file on the personal 
compaten 



)LOAD myws 

)COPY SEMFMR BTP BTFALL 
'myws' UFCREATE 1 
DTFALL 1 

2. Switch the personal computer into terminal mode and sign on to 
the VAX. Invoke the APL*PLUS System for VMS, then: 

)LOAD SERHOST 
'^myws* UFCREATE 1 

3. Switch the personal computer back into local mode, then: 

1 SENDSFILE 1 



4. When the transfer is complete, switch the personal compute into 
terminal mode. If the file is a transfer file, reconstitute the 
workspace as follows: 

)CLEAR 300000 H As large as necessary 
)C0P7 SERHOST LFF LFF 1 

. . . (objects are defined from transfer form) 

) ERASE LFF DTE DTFALL 

)SAVE myws 



Summary of VMS m Personal Con^uter Transfer Using SERXFER 



\. Jl^i^Bpsssiy, oeate the transfer file on VAX: 



)LOAD myws 

.)COPY SERHOST DTF DTFALL 
'myws' UFCREATE 1 
DTFALL 1 
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2. On the personal computer 

)LOAD SERXFER 
'myws* QFCREATE 1 

3. On the VAX: 

)LOAD SERHOST 
(Make sure the source file is lied to 1) 

4. On the personal computti: 

1 GETSFILE 1 

5. When the tiansfa- is complete, a transfer file can be reconstituted into 
a w(Hlc^pace on the personal computn: 

) CLE An 

)COPY SERXFER LLF 

LLP 1 n Restore the w(vkspace from transfer f(vm. 

... Objects are defined from transfer form 

) ERASE LFF DTF DTFALL 
)SAVE myws 

Ffx more infiHtnaiW m n^g some of the functions in the SERHOST 
wcHkspace. see Cbapux 4 of the APL *PWS System Reference Manual. 

6-4 Using the TRANSFER Workspace 

An alMliii^ tnm!<f^ method that requires more pn 

is a native file transfer, which serves the same funcfion as the 
component uansfer files used by the SERXFER protocol. The 
transfer file is a native file etsieuning character vectors delimited by a 
specific character (the default is OTCBEL). Each character vector is 
the representation of one APL object in the same "transfer form" as is 
used by the SERXFER woik^pace. 
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The TRANSFER woflcspace conains tfie ftmctions BTFN and 
DTFNALL, which build a native transfer file, and LFFN, which 
reconstitutes a workspace from the native file transfer form. 

The syntax of these functions is the same as DTF, DTP ALL, and 
Lff in the Sf/ejffffi and S£«//OSr workspace. A more detailed 
■c. r ^^e^p^ is provided in chapter 4 of titeRel(»enee !^ 



The native transfer file is the recommended technique for exchanging 
>miss§akies wiitemadiiiies imn^ Ab A1L*H4JS %staB fer 
UNIX. ItcanalsobeusedfOTlnms{eisw^ theAFL*FLUSPC 
System. 

Summary ef the THANS^MS Functions 

names DTFN deno 

. 'J Z^TFAT takes a matrix of noffiej as the left argument and 

writes the corresponding objects in scHHce QOde 
, native file tied to tieno. 

Z?7F^^LL t£dcesr a native file /isio m Oms right argument 
and writes the entire contents of the active wortsspace to the 
corresponding native file. 

LFFNisilmAtiisAveBhtiemisi^ 
recreates the active wodE^pace fixm Its coidents. 

'I- ' '.xlf < ^&mfol , size ) UNBLOCKS Henol 

UNBLOCKS takes a native file tienol and file size as its 
left argument and unblocks the file to the file correspon^ng 
to tienol. The result is a sequential STREAM_LF file. 
Since Kermit builds files in 512-byte blocks for 
transmission, the de^Bid^e of the file must be specified so 
that UNBLOCKS can remove the padding on the last block. 
Get the size by performing a UN SIZE on the original file 
on the other system. 
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The translate table i^TRTUNXTOVMS is also provided in the 
UTILITY workspace. This variable is used lo translate characters 
fiom their representation in APL*RLUS System for UNIX to the 
APL*PLUS System for VAX/VMS. The character set used in the 
APL*PLUS System for \AX/\MS is the same as that used in the 
AFL*PLUS PC System. Theiefore, translation is not needed to n^ve 
workspaces from the DOS environment to VMS. The translate tirt)le 
may be apphed by removing the comment symbol (n) from line 
[13 ] of function LFFAT. 

Summary of the Native File Transfer: UNIX to VMS 

1. Btiild the tiaisf(»-ffle on the AH,«I^US System for inNilX: 

)LOAD myws 

)COPY TRANSFER DTFH DTFNALL 
<MYVS.T' mCREATS "1 

DTFNALL "1 

SIZE'^QNSIZE ~1 fl Note size of the file for step 3 below 
nNUNTIE -1 

2. In UNIX, use Kermit in image mode or any other file transfer 
program that will tiansfa- binary data to move the file to the VAX. 

3. Run the APL*PLUS System on the VAX, then: 

)CLEAR 300000 (as large fisfnecessa^} 

)COPy TRAHSFERFNS LFFK hTSTtmXTOVMS mBLOCKS 

'MYWS.T' DNTIE "1 
'MYVS.S' DNCREATE '2 

(.~l,sae) UNBLOCKS ~2 nOet size from step 1, above 

Modify the function LFFN to translate between the two DAV 
orders by deleting a siitgle n as indicated in the fimction itself. 

LFFN -2 

)ERASE LFFN DTFN DTFNALL UNBLOCKS 
)ERASE MRTUNXTOVMS UNBLOCKS 
QNUNTIE -1-2 
)SAVE myws 
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6-5 Using a Source Level Transfer 



The functions in the SL T workspace conform to the Workspace 
Interchange eoovendcHi (as described in the ISQ^SI ML strntaid) 
for converting APL functions, variables, and environmental 
information into character variables called canonical lepmmts^nsa 
vectors, or CRVs. The Standard also presciltes a feetndqiie fer 
mapping a sequence of CRVs into a bit stream for transfer to another 
installation on a physical medium. The technique permits transfers 
between aOy tm APL systems. te^mSkss of character sets or the 
inteo^ leiHesenlatioiis of charactos. 

The following overview summarizes the procedures for transferring 
-,. . .. workspaces from the APL*PLUS System and for installing transfers 
from other systems onto the APL*PLUS System. For details on the 
functions in workspace SLT, see DESCRIBE in the workspace and 
the function descriptions in Ch^ter 4 of the APL *PLUS System 
Reference Mtmm^. 

Tranter FROM the APL *PLUS System 

; • i ..w ]L-: Condition the workspace. The workspace should be loaded using 



)XLOAD if appropriate. All functions should be unlocked and all 
gtobal vsdables should have tiieir correct values. 



)COPY UPL.RELniSLT 
SAVED 17:l6tS4 08/13/87 

3. Send the workspace to file: 

DUMPVS 'MYFILE.SLT' 
FILE SIZE'. 3218 

DPP 

nio 
ncT 

URL 

DLX 

UELX 

UALX 

NAMEl 

NAME2 

NAME3 
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FILE SIZE: 8943 



4. Repeat the above steps for eaeh workspanx to be transferred. 



S. OuQ)ut files can then be written to tape or transferred to another 
system by a file transfer utility such as Kermit (see Section 8>S). 



Tranter TO the APL *PLUS System 

1. A Source Level Tran^ file must be read into the VMS System using 
a file transfer utility such as KermiL 



2. Use VSLIf to produce a catalog of the transfer file: 



)LOAD SLT 
SAVED 17:15:54 08/13/87 

rHYFIlE.SLT* QNTIE "1 
VSLTB -1 

OFFSET: 961 VSID: VS TRANSFERVS 

OFFSET: 14014 VSID: FILE TRANSFERFILE 

OFFSET: 50868 END OF FILE. 



S. BiiagHiawoikspacefirDmthefile: 



'VICTEST' LOADVS "1 961 
OFFSET: 961 VSID: VS TRANSFERVS 
DPP 
UIO 
UCT 
URL 
ULX 
UELX 
UALX 

MAINFUNCTION 

SUBFUNCTION 

VARIABLE 

OFFSET: 14014 VSID: FILE TRANSFERFILE 
SAVING VICTEST 

VICTEST SAVED 17:59:31 08/13/87 

Noie diit the filed w(x-lc^ace is automaticalty crE»ted and stved. The 
second element of the right argum^t of LOADVS is the ofGset for the 
wodi^pace to be loaded. 

4. Repeat the above step for c^ch wcHkspace on the transfer file. 
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6-6 ConmunicatU^mthXfther Machines 



There are two facilities for transferring non-APL files directly from 
- t^: , otha- machines to the VAX: the VMS command SET HOST, and 

Kermit. Kermit is an implementation of the popular KERMIT file 
transfer protocol, which can send and receive native files between 
t^i?Rn.i 'I p . . :-. , <(^,iv; jjV, -^r.i. MT^teMApi^lehaidware and diffioKiitqpaaiiiig systems. 

9ST Command 

The VMS command SET HOST provides a means of connecting 
your terminal to another system. It allows you to communicate 
throu^ a DECNET node or a hardrwiie bom your sorial port. 

Ibise a DECNET node, Syntax fiir SET HOST Is 



$. SET HOST node 

where node is the number of a DECNET node. To commanicatB wifli 
another machine through a serial port, the syntax is: 

! - . .^ ■> $ SET HOST /DTE TXAn 

whoe TXAn is the name of a serial port m your machine. For d^aUs 
■ ' ' and a list of options to go with the SET HOST command, use the 

■ ' VMS Help facility (HELP set host). To terminate the 

oonoeetf^, hit CtrlA (Control lesy and ASCII backslash). 

The SET HOST command can be used to transfer data between other 
machines and the VAX by using the /LOG option. The /LOG option 
keeps a record of your session in the VMS file SETHOST . LOG. Once 
you are connected to the other machine, any data that you can display 
ouiplr saeen can be found in the SETHOST . LOG file. 

■ • . -^ :--••! n^^^ficrflw'VMS data buffers can ov^ow when you are 

communicating at 9600 CPS, data can be lost using this transfer 
m^hod. We recommend setting your terminal speed to 1200 CPS or 
1essii<^hennishig the /LOG option fOT 

Fot moving large data files from other systems, the Kermit utility, 
' ■ d«i»ibedindienextsec^.isabetmtooL 



ThtSETHi 



■■'■ J:- y :s- 
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Using Kemit 



The file [apl . RELn] kermit .exe distributed with the 
APL*PLIJS System for VAXA^S is a stand-alone program that 
uses the popular Kermit file u^nsfcr protocol defined at Columbia 
University. The Kermit program is distributed free of charge by STSC 
wHh the pennission of Gbtutnl^ University; it is not considered to be 
part of the supported APL*PLUS System. Columbia's policy on 
distribution of Kermit is reproduced in Appendix D. Users who require 
fiiU K£mdt dbetDaoNitation GV Ibe code Ken^ 
should contact Colombia Univmsity. 

We have found Komit an effective technique far tmeietring files 

between different UNIX systems, and between UNIX and non-UNIX 
systems such as VMS. We suggest that users who And Kermit useful 
make a contribution to Columbia University to help ftmd this valuable 
sorvice to the computing community. 

Kermit starts in "command mode," but can operate in either "connea 
mode," in which it serves as a terminal emulator for logging onto a 
remote system, or in the "send" or "receive" mode. When transferring 
files that contain other than ASCII text (for example, a source-level 
workspace transfer files) the file type must be set to binary. 

Before Kermit can be used, the KERMIT . EXE fJe must be installed 
with L0G_I0 privilege. A typical input sequence that will stan 
Kermit is: 

$ RUN KERMIT 

C-kermit> SET LIME TXAn 

C-kermit> SET SPEED 9600 
C-kerniit> CONNECT 
$ [Return] 

Kermit is sensitive to parity. If Kermit does not respond, check your 
parity setting for your me^M. For an HDS Imnhsid for oifmifde, 
parity must be set to "spaCe." When using a PC as a taminal, parity 
must be off, with eight-bit data and one stop bit. 

For more information on the use of Kermit, use the Kermit help 
facility. The help facility is accessed by entering a ? from the Kermit 
prompt. 
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Using APL wMi Non-APL Programs 



This chapter discusses the variety of ways that you can use the 
APL* PLUS System to interact with non-APL programs, such as 
ppeiating systons and other languages. 

There are three basic techniques for communicating with other 
programs from APL. From simplest to most complex and interactive, 
they ace: Native Files, UXP, and DNA. A section in this chapter is 
d^^^each. 



The Native File facility is the loosest coupling with non-APL 
prograriS. You can read and write data to a native file with a set of 

built-in functions. Then you can leave APL, either with ) OFF, or 
temporarily with ) CMD or DCMD and run the non-APL program 
' iosl^^ dam in the nati'^e file. Finally, you can r&i& Ihe result or 
any new data back into the APL workspace using DNREAD. The 
system fimction UCMD allows you to perform these steps under 
program control. 

To run another non-APL process simultaneously with APL, the 
APL*PLUS System provides the external process interface, DXPn. 
Each system function (DXPl, UXP2, UXP3, □XP4,and UXPS) 
is the complete interface to one external process, permitting as many 
as five extonal processes to be running at once. 

the system function UNA provides the facility to incorporate 
non-APL code as part of the APL workspace. This allows APL 



functions to be built from programs written in other languages. 

rn>i «. ri .■ • >jr -. 

^ • • ^ J.J Using Native Files 



Native VMS files can be accessed from APL with the native file 
system functions. These system functions parallel the suite of 
component file sys^ ftuietions, such 1$ WPtUMAfS mi 
UFREAB, but have the letter W as a prefix {UUCJREATE and 
UHREAD) instead of the letter F. 



For a iKief tunstial on the fimdamentals of native file use, see "Sample 
Kindling of Native Hies" at the end of Section 3-1. 

Issuing DCL Commands 

The system command ) CMD pomits the AFL user to execute DCL 

commands from the APL environment, and tJien return to the active 
APL workspace, if no conmiand is given, ) CiV 2} displays the 
teminda* typm log to return to apl and dien accepts a 
sequence of DCL commands on subsequent lines until given the 
instruction logout in rei^nse to the VMS {X'ompt. You are then 
mutnedtoAFL. The^taxis: 

)CMD 

or 

)CMDc(mnmd 

v^tsxt command is the DCL command to be executed. 

The system function □ CMD provides a similar capability and can be 
used under program control. The effect of □ CAfZ) is to temporarily 
exit from APL while preserving the contents of the active workspace 
and to execute the command given it, after which it returns to APL and 
excutes any code that follows. For details on the use of UCMD and 
} CMD, see the APL *PLUS System Reference Manual. 

The native file system and UCMD can be used together to integrate an 
APL program with a non-APL program. The APL program could first 
prepare some data and store it in a file in the format required by the 
non-APL program. UCMD could dien be used to request the operating 
system to start executii^ the non-APL program and use the Hie 
previously created by APL as the input. The output generated by die 
non-APL program could be stored in a file and later retrieved by APL 
after the □ CMD task completes execution. 

7-2 Interfacing APL to Non-APL Programs 

The APL ♦PLUS System provides two distinct facilities fOT calling 
non-APL programs from the APL environment: 
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External routines msqyped into the APL process's address space can 
be associated with APL names using UNA and called as though they 
. were defined functions. The facility is similar to that provided by the 
■;■ FASTENS utilities in the APL ♦PLUS Mainfirame System and by 
□i\f4 in IBM's APL2 Program Flroduct. 

External processes are complete modules that APL runs as 
subprocesses, exchanging data through VMS mailboxes. The facility 
is very similar to the external process interface used in the 
"iS^^PLUS System Cor UNIX. 

The two facilities i»ovide quite different capaUlities. The appropriate 
fecility to use depends upon the nature of the program being interfaced 
to APL. As a rule, extenutl routines are used to make discrete utility 
subroutines available to APL programs. Hiese may be tisefiil runtime 
library routines or fast implementations of algorithms that are hard to 
express efficiently in APL. External processes are more suited to 
intofacing Ml« M odier sabsyi^^ 
I • packages. 



• External Routines are mapped into the APL process and share the 
same address space. Tbey on, therefore, operate cm objects in the 
APL workspace. In contrast, external processes execute in a separate 
address space, receiving copies of APL variables passed through a 
nuulbox int»£ace. 

• The external routine interface is simpler to use than external 
processes, particularly if the routine already exists. Once UNA has 
been used to describe the routine to APL, APL will automatically 
pass parameters of die correct type to the rdutfiie whenever if iS 
called. The external process interface requires that the programmer 
understand the internal form of variables in the APL workspace and 
wr^ code specffically to process AI^ vai^bles. 

• External routines must be linked into sharable modules and the full 
names of dieiesolting . EXE Gtes must be defined as logiod names 

to VMS. External processes need not be sharable and are invoked by 
specifying the fully qualified name of the . EXE file. 




Comparisons of External Roudnes and External Processes 
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• External routines are associated with a monadic APL fiinction in the 
woilE^asei ea^ loutine neqinies a disdnet AFL funetion mm and 
uses a Sffl^miiOUnt of workspace. External processes are interfaced 
thiQugh a system fimction and have no effect at all on the APL 
workspace; the effect is more like defining a new system fimction. 

• External routines are treated like user-defined functions by workspace 
operations such as )SAVE , )LOAD, )COPY and )CLEAR. 
External processes are not associated with the workspace and are not 
affected by workspace operations. 

• External routines are unable to create new APL arrays, though it is 
easy to create arrays from APL whose values can be filled in by 
external routines. An extoiial process always creates a new array 
each time it is invoked. 

• Since external routines are part of the APL process, they cannot 
execute concurrently with APL. It is possible, however, to design 
an external process so that it can execute coneurrendy with APL. 
For example, APL can start a time-consuming computation, such as 
a large database transaction running in an external process, without 
waiting for the bansaction to complete. 

• External routines are restricted in the kinds of operating system 
services diey may use, while no ^cfa restrictions qi^y to extiamal 
processes. For example, if you wish to process RMS ffles from 
APL in ways that are not provided with built-in system functions, it 
is wiser to write an extm^ proce^ for Ms purpose. An extmid 
process can open and close files with no side effects on the files that 
have been c^ned by APL. Also, external processes can request 
memory allocation firom VMS, and use variables to preserve 
information between calls. External routines generally use only 
their own automatic variables and the data areas passed to them as 
formal parameters. 

7-J Using External Processes 

An ^cional ptoce^ is a program that runs coneurrendy with APL, but 
as a separate VMS process or task. The ettemal process is created by 
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the APL proo^ iici tW^ matt explicitly temU^ltS^ Jef ik^L 0t until 



The program runamf aft extenial pit)cess is an itidqpendentiy 
compiled, executable module that can be executed under VMS. The 
external process creates a unique mailbox, QMBxxxx, which it uses to 
a>minmiiicate widi APL. In (he mailbox name QK^asox, 
represents the external (child) process ID number and can be observed 
by issuing the VMS command show logical/ job. Unlike the 
k laical VMS piDgiam, however, the input and output are not ASCII 
text, but instead are APL variables, in the internal data lepresantation 
used in the APL * PLUS System workspace. 

APL communicates with an external piDcess throi^h a VMS mailbox. 
Whoi DXPn is called, it writes first i& left and then its right 
argiuAfent into the external process's mailbox, and then it begins to 
fipa^ ^ mailbox. The external process is constructed so that it 
' ' %^^e§ two arrays, compute a tesult array, and ^Miak 
array to the mailbox. APL reads the mailbox to obtain the array that 
becomes the e.\plicit result of UXPn. 



' ^Vp^'&v^^exmaA processes can be running at once. The system 
functions UXPl, nXP2, UXPS, nXP4,and UXPS refer to these 
external processes. The monadic form of all the UXPn system 
tticticHfs Controls the interface. The ^^c form pas^ data to the 
^ten^isocess and letians compated results to the woikspace. 

An external process is created by monadic UXPn. If the right 
argument is a character vector, it is assumed to be the name of the 
program to be run. 

One of the sample external processes distributed with the APL * PLUS 
iSystnn is named Vl*OM. To inltate the process: 



DXP 1 ' LAPL . RELnl VTOM . EXE < 



8192 



The explicit result (8 192) is the VMS ID for the new jwocess. If the 
; cannot be created, a two^Iement integer vectcM' 
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is returned. The first element is 0, and the second element is the VMS 
System Service Concfition Value. 

Once the process is running, dyadic UXPn can be used to pass APL 

designed to convert a Uank-ddimited ctaaract^ vector into a matrix. 

VECTOR^' ONE TWO THREE FOUR FIVE* 

MATRIX*-' • nXPl VECTOR 

pMATRIX 

5 5 

MATRIX 

ONE 

TWO 

THREE 

FOUR 

FIVE 

Note that in this example the external process actually uses only its 

right argument. An empty vector is used as a dummy left argument 
since UXPn must be called dyadically. The program VTOM will read 
but ignore die left argumoit. 

You can query the name of the program ruiming as an external process 
hf etfUIng QXPn monadically widi aa maptf aigument: 

axpi • ' 

lAPL.RELnVTOM.EXE 

If the result is empty, no external process is presently running for the 
particular UXPn system function: 

pnxpi • ' 

12 (DXPl is alrea(ty being used.) 

pDXPZ ' • 

0 (J1XP2 is currently available.) 

To tenninate the extmial process before the end of the APL session, 
£neeing UXPl for re-use, use monadic BXPl with a numeric 
aiig^nnent to signal the external process. In the case of vtom, the 
untiaf^le "kill" agnal (9) will wc^ 
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0 



The 0 indicates that the external process is no longer running and 
□XP 1 can be re-used. In the current release, the only acceptable 
numeric argument to monadic DXPn is the scalar 9, which teiminates 
<i u\i jvi-: L--< r . f/i--: I .\>^. . the external process. Any othwDumbw produces a DOMAIN 

ERROR. 



.■»H .•■X,v- -.t^\- . H ciury'.iP ■hjv.f '^<VmxmmM^mlXm Process 

' > 'j-i'.'M .'. a u.M' ■ 

--' •' - '1 While an external process is being developed, it is useful to use 

■•. ..s v; ■i->,,-,,: ■■ f print f to display messages that trace the status of the program, 
v;-; . ,x The sample external process source file VTOM . C contains examples of 

'1'^ . ;(•-■;..■..•»•.= ' this debugging technique. Output produced by fpriatf is (B9t apart 

of the logical screen image maintained by the APL S(Bsa(ni Manage, 
so it disappears when the Re&esh key is pressed. 

If UXPn indicates normal creation of a process, yet the external 
process does not function at all, the problem may be that system 
t / . . . . !, . . . . , quotas have beoi^ceeSidpertmiDgtte^iem ton siMing the 

process. You can check fo see if the process is running with the 

following command: 

)CliD SHOV SYSTEM 

The operating systmshoidd display die XP/txm process. If it does 
not, check your quotas widi the VMS cCHQimaid: 

b 4.«.''..v; xd:-^. ,v ji.-.s^ SHOV PROCESS /QUOTAS 

■'i«ui> -kb sinvlToia <n fv. ■■ r-,, , The open fite, stibpTOcess, pa^g fflfr, fflid baff(H«d I/O byte count 

.. . - v , -_=,v , quotas are affected by each external process. Additional information on 

the appropriate values for each of these quotas is provided in the 
APt*PWS System Installation Manual. 

Stopping an Orphan External Process 

y The VMS command show system displays a list of process IDs 

and names. The name of an external process is 50>n»cia where n 

represents UXPn and the xxxx represents the process ID number of the 
parent process (APL). If APL has terminated abnormally, leaving an 



orphan external process still running, the external process is stopped 
by issuing the VMS command stop/id=}'}y, whwexjyis the 
process ID of the XPnxm process itself. 

The programs lhat run as external processes must be specifically 
written for this purpose and conform to the input and output 
conventions of OXP 1 . These programs can be written in any suitable 
language, inovided the resulting program is a VMS . EXE fOe. 
Typically, the external process is used as an interface to a library of 
subroutines supplied with a software package such as a database 
mmg&. The external process is a relatively simple {Hogram that 
forms a front end to the package, interpreting APL arrays as control 
information or data, and dispatching the appropriate subroutines. 

Programs written to run as extranal processes need to obey the 
ftdlowing conventions: 

• All input read from the mailbox QMBxtxt will be provided by APL 
in the internal form of an APL variable. The structure of APL 
variables is explained in the file VARMAC . H l&^lbuted with the 
APL* PLUS System; this file also contains macros tO be used for 
constructing and manipulating arrays. 

• All output written to the mailbox must be in the same format as an 
APL variable. 

Following is an outline of the structure of a typical ext^nal process. 
Sample external processes are provided with the AH- * PLUS System 
in both executable and C source forms. Users who want to write their 
own external processes are encouraged to begin by studying the sample 
source Sles. In many cases, it is practical to moiky tm ot the sample 
pK^grams to perform the task desired. 

S^mm efan Externa Process 

The general structure of a typical external process is described below. 
For aiSlMximl dStHflsimd co^g tedudques, examine the following 
fdes distributed with this AF1*PLUS System: 
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extomal process called [APL.REliAlVfOM.sxE 
• FILE . C C lioiguage native file interface for VMS 

- " .' li 

' ■' • VARMAC . H C language header file describing the structure of 
APL arrays as used in the external process interface 
and containing macros fot accessing the fields 
within the array 



' ERRMACRO . H C language header file containiqg the eaot codes 

used to signal specific mots fiom UXP miSm AH^ 
oivinnunent 

• Set traps for any signals that may be sent by the application. If no 
■.va .i^i^n ajt) m^sae set. any signal will terminate die extonal process. 

• Initialize other variables or open files as the application warrants. 
The mailboK is oeated for inter-process conmunication here. 



Main Program - Main Loop 



• Read the DXPn left argument (an APL array) from the mailbox by 
reading up to 5 1 2 bytes into the local buffer. The first 4-byte field 
is a 32-bit integer indicating the size of the array in bytes, including 
the 4-byte field. If the array is larger than 512 bytes, read the rest of 

^ the viEiriable into a suitably large huWa. If Ae rOEui fiarmimdes wiOt 
fewer bytes than oqpected, go lo exit 

..•li/' 

' • R«»dilie UXPn right argument fem die mailbox by die same 

technique used for the left argument. You must read the entirety of 
bodi arguments out of the mailbox, even if one is a "dummy" 
ifitUnait, to dyadic QXPn. 

• Interpret the content of the APL arrays by using the appropriate 
maeros to access die datatype, raiik, sbqie vector, and data values of 
theaoay. 



• Perfcm whatever processing is apprqniate. 
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• Construct the APL array that is to become the explicit result of 
□ XP 1 by writing the appropriate values into an internal buffo' 
variable. You must fill in the following fields: 

leading length (4-byte integer) 
descriptor (type) byte 
rank byte 

numbear of elements (4-byte intega) 
shape vector (4-byte integers) 

data value; padded as necessary to fiU out to a 4-bytB boundaiy 
trailing length (4-byte integer) 

The routine initbuf ( ) in VTOM . c fills in all but the shape 
vector integer(s) and the data values. The 6 bytes between the 
leading onattfie^and die des(3q)tar fidd can taaw 
aie best set to zero. 

• Write the result array to tteinailto. APL will wait until the entire 
array has appeared in the mailbox before allowing DXP 1 to return it 
as an explicit result. 

■ Go to main loop. 

Exit 

Close the mailbox and terminate. 



7-4 Using External Routines 

After an external routine has been defined in the workspace with UNA, 
it can be used as though it were a locked APL function. External 
routines are always mcmadic; they are called with a right argument 
whose shape is equal to the correct number of parameters for the 
external routine. Typically, the argument to an external routine is a 
nested array, in the form of a vector of arrays, in which each item 
conesponds to a parameter to the external function. 

The explicit result of the external routine is a vector of those items 
specified as output variables by QNA. If the non-APL routine 
generates an explicit result, such as a return code, and this result is 
described widi QNA, the result becomes the first item of the result 
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returned to APL. Additional items in the result consist of any 
parameters designated as ou^ut variables, in the otdet in which they 
appear in the parameter list. 

For cacainple, sappox an external routine named i sum exists, whose 
effect^ to add iq> a vector of integos and letum a scalar containing 
that sum. In C, the functioi could be ejqnessed as foUows: 

int svim ( input, length ) 

int *input; /*address of first number in vector 
int length; /*length of the vector */ 

int i; 

int sum = 0; 

for ,( i-0; Klength; i++ ) { 
sum +- input [i] ; 

} 

return (sum) ; 

} 

Also, suppose that this routine has been compiled and UbIsbA, and dial 
the resulting . EXE file has been defmed as a logical name SUMFNS 
(see "Writing Your Own External Routines" for details). To bind this 
fincttett^fd Al^ Qltil would be iml as fiDltows: 

3 0 MA ^simHSitmm isum (.*ia. ia) ia' 

1 

This tells APL to create an external function in the workspace named 
A SUM, which is bound to a routine named isum that can be found in 
the shared module wifli logical name SUMFNS . The explicit result of 
, , , 1 indicates that the arguments to QNA were well formed, but it does 

not necessarily indicate that the extemal routine can be called with 
diese arguments. Since the specifications for parameto^ are not 
" 'Si^xu preserved in compiled code, it is extremely important to provide the 
correct information to UNA. Unpredictable results, including an APL 
sys^ oash, can be caised by inconm use of external routines. 

. , , . Qnge^lbe external function has been bound to an APL name, it is for 
{^ {xactical purposes a locked ftmction in the woricspace. For 



Copyn(^& , 7-11 Usmg APL with Non-APL Programs 



)FNS 

hSUM 

DNC 'aSW 

3 

)SAVE SAMPLE 

) ERASE ASa« 
)COPY SAMPLE ASl/« 
SAVED . . . 

As defined to APL in the above example, the function a SUM is called 
with a 2-iteni nested vector. The first item is the vector containing the 
nimibef to be sunimed, iptf tfie secwd is a scalar ccmtaining 
of the vector. Rxroample: 

ASVAf (15) (5) 

15 

It is often convenient to define a com' functioo for an otienial routine, 
for example: 

V Z^SUM R 
[1] Z^i^SUM (.R) (p,R) 
7 

How APL CttWi External Routines 

After an external routine has been defined to APL with UNA, it can be 
in^dtedljy eallii^ it is a monadic Ametioo and supplying tte isop@r 
right argument When an external routme is called, AfL performs the 

following steps: 

• Check the right argument to make sure it is a scalar or vector whose 
length matches the number of parameters that were specified with 
UNA. 

• Btdld a standard VAX architecture argument list containing data 
(Eactracied torn the items of die right argument. 

• Locate the module ao& routine, mapping them into die AH^ 
process's address i^iace if diey are not diere alr^y. 

• Call the routine, i»ssing the argument list. 
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When the routine returns, build an APL variable ta c(»itain the 
explicit result and return it to APL. 



When an external routine is called, APL constructs a standard VAX 
argument list from the right argument supplied to the external routine. 
.. Ihe argument list ccmsists of 4-byte parameters that contain either the 
datavalueitself (which is caOed "pass by value") or an addressed the 
data ("pass by reference"). The maximimi numbo' of paiametm Aat 
the external routine may have is 23S. 

If an argument is passed by value, APL requires the corresponding item 
of the external routine's argument to be a scalar, whose value is placed in 
the 4-byte field. Double-fmcisnon floating liNns esn be passed by 
value, taking up two successive 4-byte valuetS. litis is the same way 
that the VAX C compiler passes doubie-preci^OB floats by value; most 
ofhei VAX languages pass only single precision (4-byte) floa^ by value. 

If the argument is passed by reference, APL passes the address of the 
first data value of the corresponding item of the argument. For 
^(^ple, if a routine has two arguments, both passed by reference 
t*T4 , * CI ) , it would require a 2-item nested array as its argument: 



. . i fi -■ V 1 • 



ARG *■ ( 99 100 101 102 ) {<ABCDEFG') 

The external routine will be passed an argument list that contains the 
address in the workspace of the value 9 9 in 1 =>Ai2G, and the address 

. Arguments of type GO (general APL objects), are always passed by 

xt a<viJiK>i ail) titer i. . j' j. ' ,, reference. APL passes the address of the APL array itself rather than 

•'• ' the address of its data, which begins a few bytes into the array. The 

r,9fe - , external routine must be written with a knowledge of APL array 

'ixu :'of, r'< ^ffi ;i xt-i^^ ^'gnictiEe. See the preceding discussion of Exteaiiai Process^ for hm^ 

' - • ■ K -.. . V . .oo^^i^Larray structure. 

Because of the efficient form that the APL*PLUS System uses to 
create and represoit nested arrays, the execution cost of fomiing a 
■'■^ ^' nested^array argument to an exteiaalfQatbie is negligible. There is 

very little ov^iead in building the argument in instances like the 
following: 
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r *- PROCESS (ARGl) (ARGZ) iARGS) (ARGA) 



Automatic CmversUm ofNumerk Datatypes 

APL uses three different datatypes to represent numeric values 
(boolean, intego', and floating point). If a numeric amy is passed as 
the argument to an external function, APL will automatically create a 
copy of the array in which the values have been converted to the 
datatype that the external routine expects. For example, the functi(m 
^SUM described above could be called with inte^ values in any 
datatype: 

r - ASUM (1 0 1 1)(4) n BOOLEAN VALUES 
T <- ASUM (1 ♦0-10 0){4) tt tmEQER 
T *■ ASUM (1£-12 * 1 0 1 1)(4) n FLOAT 

Floating point values will be converted to integer only if they are 
within APL's "integer tolerance" of a whole number. Values that are 
not ctose so a ^ole iiHiega produce an enor. 

T *- A5[/W ( 1.5 2 3 ) (3 ) 
DOMAIN ERROR 

T ASUAf (1.5 2 3) (3) 

A 

Explicit Results for External Routines 

The explicit result that an external routine returns to APL is formed 
from the result of the routine (if described in the UNA description) 
followed by any parameters marked as ou^ut arrays with ' ' in the 
UNA descriptioa If any ouQJut arrays are passed by reference, they 
will be returned as enclosed items of the result. If ^e routine is 
described to UNA as not returning a result, by omitting a result 
specif icaticHi, any result produced when the routine is acuially called 
wSl be dtsearded. If no result and no ouQxit variables are specified, the 
external routine returns an empty num^ matrix (0 0 pO ) . 

Output arrays pronde the medimiism by which an external routine can 

return an entire array to APL rather than a single scalar. For example, 
consider an external routine REVERSE that reverses a character 
vector. It expe^ ftree parameters the address of input vectcnr, the 
address of the output vector, and the length: 
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3 0 UNA *SMPLFNSiREVERSEi*Cl,*Cl^.I4) 



When SfV^Bf^fetalled ftm APt, its second pvameter must be 

the array that it will modify to contain the reversed character vector. 
This array should be of the same sh^ as the first pacanieter, which is 
the input. 

Since APL always makes a copy of an ouq}ut array before passing it 
to the extmtal routine, the simplest way to call this routine is to pass 
^.j^^iuiay as both arguments: 

r ,■ ^^j, ^ INPUT UNMODIFIED' 

TXTR - ^REVERSE {TXT ) iTXT ) ipTXT ) 
TXTR 

DEIFIDOMNU TUPNI EHT 
TXT 

THE INPUT UNMODIFIED 

If the array returns more than one item in its result, strand assignment is 
convenient for breaking up the nested array result. Suppose REVERSE 
also returns a return code to be letumed to AFL: 

)ERASE REVERSE 

3 ©• aNA ^SMPLFNS : REVERSE ( *C1 . ♦C1-, 14 )r4 ' 
fi£yffiS£ will now return a 2-item vectta: 

RC TXTR - REVERSE (TXT) (TXT)(.pTXT) 

It is important that all arrays that might be modified by the external 
routine are marked with ' <- ' by UUA. CiE»iS^ die eH^ of not 
madking tte output anay in the above example: 

IBRASE REVERSE 

$ 0 MA 'SHPLFNSt REVERSE i*Cl.*Cl. 14)' 
TXTR *- ^REVERSE (TXf y(fXT)(.pTXT) 
TXTR 

DEIFIDOMNU TUPNI EHT 
TXT 

DEIFIDOMNU TUPNI EHT 

APL passed the same address as both the input and output, with the 
consequence that the external routine modified the input variable as 

well. Since no copy was made, the variables TXT and TXTR refer 
to the same array in the workspace. 
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Caution: Unless care is taken to ensure that only one variable name points to an 
array, it is unwise to modify an existing anay in the workspace. For 
example, 



careates a single copy of the array i 1 0 0 0 and causes three variable 
names to refer to it If the contents of A are modified by an external 
roti^, by passing A by reference and not defming it as an output 
variable, B and C will be modified as a side-effect of modifying A. An 
example of when it is safe to modify a named array can be found in 
"Vam Study: Vector to Matrix Conversicm," in this section. 

Errors Produced by Calling External Routines 

The following errors may be produced at the time that an extonal 
routine is called: 

RANK ERROR The argument is not a scalar a vector. 

LENGTH ERROR The shape of the argument does not match the nunbo^ (tf 
piuaiaeters described to UNA. 

DOMAIN ERROR The datatype of an item of the argument does not match the 
type specified with UNA and the data can not be converted 
to required type. DOMAIN ERROR is also produced 
when APL is unable to map the external routine into its 
address space. This can occur for a number of reasons, the 
most common of which are: 

• The logical name of the module is undefined. 

• The .EXE file associated with the togical name does not 

exist. 

• The . EXE file contains no entry point with the specified 

name. 

• The module is not linked as sharable. 
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Future versions of the AH.*PLUS System wffl permit pa^iig 
, > , • arguments by VMS descriptor, a common practice in the VAX 
environment. In the current release, you have to write your own 
uaBm^mma&asi fbatacaipt the currently suiqxHied Smu^p^ and 
set up calls to routiiies that ^cpect paisuneters by desci^^ 

M^b^IpjtrOmtMJOenui Routines 

External routines can be written in any suitable language, including 
FORTRAN, PASCAL, C, BUSS, as weU as assonbler. The only 
restrictions are: 

• The routine must accept parameters passed standard VAX 
^ aiguinent lists. 

• The routine must use iMffameters of ^pesdiat are accqjied by 
QNA. 

The procedure for writing, compiling, and linking a module that contains 
routines to be called from APL is summarized by the following example: 

1. Edit the source file. Sui^ose an editor is used to create a "C" 
language source file StnffiVS . C with these contents: 

' ' "^'^ isum(a,n) /* sum an integer vector «/ 
. int *a; 
int n; 
{ 

int z = 0; 

while ( — n >=0 ) z += *a++; 
return (z) ; 

} 

double fsum(a,n) /* sum a float vector */ 
lOi; : .iT.jJ',' j^i^le *a; 
inf 
{ 

■ ^' ~ •- doilMe z = 0; 

while ( — n >= 0 ) z +- *a++; 
return (z) ; 

) 
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2. 



Compile or assemble the source file. In this instance, the DCL 
conunand to compile a C program is: 



$ cc sumfns 



3. Link the object file as a sharable module, specifying both routines 
as universal (externally visible) entry points: 

$ link/share sumfns, sys$input : /opt 

(User types as many linker 
universal=isum options as needed and types 

universal=£suin Ctrl-Z to indicate end.) 

4. Define a logical luune for the module: 



$ define sumfns $duaO: [jgw.textl3umfns.exe 



5. Run APL, and use UNA to bind external functions to the routines: 



3 0 QNA ' SUMFNS ;ISUMi*IA, 14)14' 

1 

3 0 DMA ' SUMFNSiFSUMi*DB ,IA)DS* 

1 



6. Use the external routines: 



I SUM (1 2 3X3) 

6 

FSUM (1.5 10.4X2) 

11.9 



Calling Runtime Library RouAnes 

Routines in VMS runtime libraries can also be called from APL as 
external routines. For example, the VAX C runtime library routine 
t dimes ( ) returns information on how much CPU time the APL 
pocess has consumed. Its C syntax is: 

int tim^s (t) 

int t[4]; /* where values will be placed */ 

The VAX C Runtime UlxBry is assumed to be equated with the 
logical name vaxcrtl, so an external routine can be defined thus: 
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^ " 3 0 UNA 'VAXCRTL-.CPUHTIME TIMES (*I4'^)' 

• -• •• 1 

The monadic function CPU^ TIME now can be called, passing a 
4-element integer vector by referraice. The fimctioii tiroes ( ) will 
wiite its result as this address: 

' .^r *- ^CPULTIME ci4 
4 

T 

234 ,0 0 0 
CaseStiufy: Veetmr to Matrix CoKversioH 

This exwnple^hews tow to deal wiifa die testnetion that external 
. . , . , routines cannot create new APL arrays but can only modify the values 

of arrays that have been passed to them. A program that converts a 
delimited vector to a matrix must examine its input before the shape of 
the result can be calculated; and the sh^ must be known before the 
output array can be created. 

The problem can be solved by splitting the calculation into two 
external routines. The first examines the input, calculates the 
" '' dimensions of the result matrix, and returns them to APL. An APL 

statement then uses reshape to create a matrix with the correct shape 
anddaiat^ The nuora is tossed fi3dKsee{»tfvoiii!iBii^ 

i ^ ■; .T\ ; If r-.' sltei^thgitwo routines couM be defined with the^ 

■ " ' "TitSMlrtiii vmshape 0 calculates the shape needed for the result 

matrix and vmfill ( ) fills in the values. 

vmshape (input, len, shape) 

char *input; /* delimited character vector */ 
int len; /* length of input vector */ 

int shape [2]; /* where #rows and tools are placed ' 

f 

int nrows; /* number of rows needed in result */ 
int ncols; /* number of cols needed for 

longest row */ 
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/* ... scan input, calculate nrows and ncols 
shape [0] = nrows; 
shape [1] ■= cols; 



vmfill (input, output, shape) 

char *input; /* deliniited character vector */ 
char *o\ieputi /* 6hat«#t«r aiatxix */ 
int shape [2} /* shape of output */ 
{ 

/* ... scan input, copy each delimited string 
to a row of output ...*/ 

) 



Afto' these routines have been compiled and linked, they can be defined 
as external functions: 

3 0 UNA *VT0H:VMSHAPE(.*C1.IA.*IA*-)' 

1 

3 0 niHA ^VT0M:VMFILL(*C1,*C1<-,*IAV 

1 

The two extonal RMdines can be incorporated into a stand-alone APL 
$ovafuncti(»: 

V MATRIX-VTOM VECTOR ; SHAPE 
[1] H Converts a del imited character vector 
C2] fl into a matrix. 

LSI SHAPE - VM SHAPE (VECTOR) IpVECTOR) 12 2) 

141 MATRIX VMFILL (VECTOR) ( SHAPE p' ') (SHAPE) 

V 

Note the use of the third parameter to VM SHAPE. A two-clement 
integer array with arbitrary values (2 2 ) is created and passed to 
VM SHAPE to be filled in. Since tfiiid panuneiar is designated as 
an output variable and included in the result, APL will create a second 
2-element vector which is passed to VM SHAPE. A similar process 
occurs with the second elemoit of VMFILL. In both cases, an AM. 
expression is used to create a new variable which is duplicated to 
become the explicit resulL Two arrays are created in each case but 
oily one is needed. 
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Efficiency can be improved in this case by passing arrays that the 
external routine is expected to modify and not marking thm as ou^at 
variables: 



)ERASE VMSHAPE VMFILL 

3 0 DNA 'VTOM:VMSHAPEi*Cl ,14 

1 

3 0 UNA 'VT0M:VMFILH*C1,*C1.*I4)< 

1 

V MATRIX'-VTOM VECTOR ; SHAPE 
[1] fl Converts a del imited character 
121 n vector into a matrix. 
131 SHAPE*-2 2 

£43 VMSHAPE (VECTOR) I pVECTOn) i SHAPE ) 

ISl MATRIX *- SHAPEp • ' 

C6] VMFILL (VECTOR) (.MATRIX) (SHAPE) 



In Ibis case, it is safe to allow the external routine to modify the 
contents of the named variable, since it is certain that the array is 
referenced by (Hily one name. The usage is considerably more 
effidenL 
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Chapter Eight 
Printing 



Because of the wide varieQr of printers used in the VMS environment, 
boA widi die VAX anfl Min&VAK. m A1^«I%U§ Pjfmsei 4im not 
yet have any standardized printing utilities. As support for various 
printers becomes available, information will be added to this chapter. 

How Do I Get APL Data to My Printer? 

Use the existing printing facilities of your printer and VMS. The 
APL* PLUS System's Native File capability allows you to write your 
APL data into native files (see Section 7-1 of this manual). Then, 
submit a print job for the native file» just as you would for any other 
VMSffle. 

Haw Do I^APl Charaeters to Print? 

There are hardcopy luminals such as the LA120 that have APL 
character sets and can p^t files tvilfi thatmm. 

Alt»natively, you can pint APL characters by using a PC (running 
die AFL*n.US PC S]^iem in trambial diode) as a terminal to the 
VAX. A slave printer attached to the PC can be made to {Hint any 
characters that appear aa the scre^. 
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Chapter 

Supplied Workspaces 



The workspaces supplied with this AM<*I'LUS System am be 
grouped into several categories: 

Kiia tefKiia 3viij^"83?;;i >. • The tutorial workspaccs are i4PLC0ySS£' and LfSSOWS. Th^ 

will help you learn and practice APL in conjunction with the 
manual APL /5 Easy/ 



'ir-^ il'iilii --itAXi O) V ' 



• The demonstraticm workspace, DEMO APL, illustrates features of 
this APL ^ston. 

• The file transfer workspaces are SERHOST, TRANSFER, and 
SLT. 5£/2//05risadatatransfaq^cationusedwith 
SERXFER on personal computus. 

• The utility workspaces are DATES, FORMAT, INPUT, and 
UTILITY. They contain helpful functions that you can use to 
format dates jWd #01, ease convert fiom 0tber ^stemei, and 
collect and process input You'll find them oselid wb^ iKiQdiQg 
your own iHQgiams and ^plications. 

• The sufjplemental workspaces are COMPLEX and EIGENVAL. 
The COMPLEX workspace provides APL cover functions to 
perform complex mmiber arithmetic. The EIGEIWM. wcarkspace 
provides fimctions to conqNde dgenvalues tmd dgenvectocs. 

Where relevant, overviews of certain woitapaces Me givoi in other 
! manual as follows: 



• IWPC/r— Chapters 

• SERHOST, SLT, and TfiiU/Sfffi— Chapter 6 

• FOff Af>4r--Chapter 4 

This chapter briefly documents the other supplied wo^c^aces. Each 
secdoii insists of rni overview and a list of tte fenea»is grouped by 
subject. Detailed function descriptions can be found in CSiapter 4 of 
\heAPL*PLUS System Reference Manual. 



Each workspace contains a DESCRIBE function or variable 
containing online documentation for the workspace. When you first 
load one of the workspaces, enter DESCRIBE to augment the 
documentation in this manual. 



9-1 The APLCOURSE Workspace 

The APLCOURSE workspace is an interactive tatoM that create 
drill and practice exercises using primitive monadic and dyadic 
functions with scalar or vector integer and floating-point data. The 
workspace corresponds to the AI DRILL workspace discussed in the 
APL text APL: An Interactive Approach by Leonard Oilman and 
Mm J. Rose (Wiley. 1984). All the functions are unlocked. 

The functions prompt for selection of the APL functions on which 
you want to be tested. You can select several function ^pes for a 
session. You must solve the problem and respond with a correct 
answer. You get three chances to solve the problem correctly. After 
three incorrect answers, the correct answer is displayed. You will be 
dtOledontheii^eftbeftnctimi^ Ifyou 
want, you cm receive a lecad of your pofoimance. 

The funet^ns EASYDRILL and TEACH create thetiractk« drills; 

the function INSTR displays instructions on using these functions. 
filSyfliJILL and Tfiic// are quite similar in action. You first 
selecithe fttnctianrad cbtatype. If vectors are used, yon can abo 
choose reduction. Tb&TEACH function differs from EASYDRILL 
in its ability to use veciKKS of length zero and to create drills with 
scalar m(Miadic, scalar dyadic, mixed dyadic, and ttaiOBdmaaB^ 
functions. The variables SM and SD contain the scalar functicms, and 
MM and MD contain the dyadic functions. 

The variables PLEASE, CHANGE, STOP, and STOP SHORT halt 
execution of the current exercise. If you have difficulty solving the 
problem, PLEASE returns the solution and creates another problem 
using the same function type. CHANGE gives the correct solution 
and switches to problems of another function type. STOP ends the 
session and displays the record of your performance. The variable 
SCORE stores the results of your session. STOP SHORT 
terminates the session without displaying your score. 
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.^M^n^m^ii^^SX Workspace 



The COMPLEX workspace contains functions that perform complex 
' c nombacompuadcmsandstnictiiralniaiflfniladonsd^ 

' Aiit.aj-^ t matrices. The workspace also includes a function that derives the 
^ complexrootsofananalyticfunctionof a single complex variable. 

The summary function provides a synopsis of all of the functions in 
the workspace. You can display documentation for each individual 
utility fimetion by oitefing: 

EXPLAIN fmctionname 

The following conventiaas are used Ifaroughout the wodcspace: 

• The notation aJb is used to reference the complex numbo* a¥bi in 
the ctocwnentation and function descr^tioiis. Purely imaginary 
iHimbets aie tcfiBceoced as QJb. Pmdy letd mmbescs, oJO, are 

■ . tAixieiaaiedasa. 

• An'anay (tf conni^ munbeis is represoiled by a nomeric array 

whose rank is one higher and whose first dimension is 2. The first 
coordinate represents the real part of the complex number and the 
second co0f<dStoiB lepe^etits imagpuunry part For eatauf^, tSA 
• - complex scalar 3 J4 (344i) is represented by the vector 3 4. The 
complex vector 1J2 3J4 5 677 OJS is reiH^esented by 
' -^^vS^l 3 § 6 0 t 4 0 7 8. IMm^kmm^-n 
compile matrix is rcp^foited by a 2-by-OT-l^-n numeric zcmf. 

• Functions that (^etalB on ait^iaiy complex arrays are prefixed CX ; 
functions that operate only on complex scalars (two^ment 
numeric vectors) are prefixed Z. 

- • The tenn "alternating string" refers to a numeric vector with an even 
number of elements where the odd elements are the real parts of 
several complex numbers and the evra demoits are the inu^inaiy 
parts of the complex numbers. 

The CX function filters an APL array to ensure it is a valid 
representation of a complex array. It also takes an alternatiqg string 
andcnganizesitasarepDSScatatimof acom|l@tvec^^ lt» 
CXRE SHAPE function can be used to create higher dimoisional 
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complex arrays. Once you have established representations of complex 
arrays, you can apply a variety of annputational functiois to ihem. 

For example, the function CXTIMES multiplies two complex arrays. 
To multiply the complex vedliQr IJ2 3 4/5 by the vector 
1J~1 2J~2 3J~3,youcaii»ecate: 

12 3 0 4 5 CXTIMES 1-12-23-3 

When both operands are complex scalars, use ZTIMES. For example, 
the statement: 

6 7 ZTIMES 8 9 

multiplies 6J7 by 8 J9. 

Odier functions are availaUe to conqmte: 

• sums, diffefonces, and quotiBnts 

• square roots, powers, logarithms, and exponentials 

• td^onom^ric and i^petbolic functions and tibeirta^ 
■ ON^Ui^, magnitudes, and amplitikles 

• inverses and transposes of complex matrices. 

Use the SUMMARY function in the COMPLEX woitapace to di^lay 
both the name and syntax of each of these functions. 

The CXROOTS function finds the roots of a function of a single 
complex variable. This funcdon must be named CX£n and must be 
monadic and return ai explicit result Bodi the argument and the result 
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must be a complex scalar (two-element numeric vector). After you 
define CX£n , execide: 

roots ^ CX ROOTS guesses 

. .. . whoe the argument is an alternating string or complex vector of 
guesses. The number of guesses suppliedlimits the number of roots 
that will be returned. The CXstate global variable conU'ols the 
behavior of tt^CX ROOTS function - the maximum number of 
iterations, tfS^m^i^e tolenuice, die display of intennediatBd 
results, and so forth. Execute CXSTATE for a review and 
intotpretation of the elements of CX s t a t e . 



9-3 The DATES Workspace 

, n»e DATES workspace contains functions for converting dates (vector 
to scalar or scalar to vector), formatting dates, v^ying dates, and 
perfonning niiscdIjHMoas «»detMcms and ffiai^^ 
based on the Gregorian calendar. Each function handles any number dT 
dates in its argument, except for DATE SPELL and DSPELL, 
which handle only a single dsoe at a time. All fonetkffls that accept 
the vector form of dates require that the argument be in DTS 
timestamp form. No error-checking is performed. Invalid arguments 
may produce errors crincoErect results. 

Conversion 

The DATEREP, HOURREP, MINREP, SECREP, TIME REP, 
and FTIMEREP conversion fimctions change dates from a compact 
base form (for example, as the number of days or minutes that have 
elapsed,;^ffie|Q|^w to, 0:(X):00, 1 January 19(X)) to a vector form 
amiiarwmeW^raiestamp. Conversely, the DATATSASE, 
mUR$ASE,MINBASE,SECBASE, TIME BASE, and 
FTIMEBASE conversion functicHis change dates from a vector form 
to a scalar form rqireseatnig tas dapsed number of lime units from 
qipO^,l January 1900. 

Formatting 

■'■ The riAfffWr.friAffPAfr, and DSPfLL functions format dates 
in fixed' fomats. DATE SPELL spells out and formats dates 
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{^cordfaig to various ^tions, and allows an hour oCEset to ttne wm& 
other than Eastern. TIMEFMT, DSPELL, and DATESPELL 
allow formatting of var>'ing time precisions. 

VerffkatioH 

the HATECHECK function verifies a date to ensure that it is a valid 
date. 

CalcidaUott 

A variety of functions in this workspace perform calculations with 
dates. DAYSBIFF miVKDAYSDIFF calculate die number of 

days or weekdays between dates. DA YOFVK determines the numeric 
value (1-7) of the day of the week for a given date; DAYOFYR 
determines the numeric value (1-365) of the day of the year. 
LEAPYR determines whether a given year is a leap year. 
DATEOFFSET calculates dates by offsetting to past or future dates. 
yWOrOWOy converts dates packed as LYMDl to dates pad^ as 
[tfCy ], and AfZ}yr 0/Afi} peifoims the inverse operaticm. 



9-4 The DEMOAPL Workspace 

The DEMOAPL workspace contains functions that demonstrate the 
diverse c^abilities of your APL*PLUS System. The DESCRIBE 
variable explains the purpose of each function. Use of this woricspace 
is discussed in Chapter 1 of APL Is Easy! The LIST function 
displays an entire function using OVR when a function name is 
supplied as the right argument M functions are unbxdted mi 
commented. 

FomuMng Output 

REPORT, CALENDAR, and CALEN demonsu^tte use of the report 
generation facility (see Chapter 7). A report typical of a business 

application is generated by REPORT. The report title is centered ova 
the table by the CENTER function. DATA. PARTS, QUAN, 
TITLE, and TOT are oeated as global variables by REPORT. 
CALENDAR creates a calendar for any specified month of a given 
year after October, 1752. CALEN uses the CALENDAR function 
twelve dmes to display a calendar for an entire year. 
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•f. 



COMB, PERMX, and PRIMES use primitive APL system functions 
to perform complex mathematical options. COMB uses a recursive 
algorithm to create all combinations of a given numto firom a fixed 
s^t of numbers. PERMX generates a table of all permutations of 
numbers from DIO to a specified number. PRIMES i^ums all 
prime numbers from 1 to a specified number. 



Tlie PIGLATIN fum^cm tianslates a chmcta string to pig<bttia. 
Extra blanks are mnoved. 



9-5 The EIGENVAL Workspace 

Hie ildMHfAL vfoOsspme^ eoiitains a variety of functions to find 

• . ^A^^, eigenvalues and, optionally, the eigenvectors of real matrices. Both 
real and complex eigenvalues are derived. Different routines 
mbodying different techniques cffii be used dqioiding upon whetha ac 
not the real matrix is symmebic. 

The summary function provides a synopsis of all of the functions in 
the wcffkspace. You can display documentation for each individual 
utility function by entering 

EXPLAIN functionnam 



9-6 The LESSONS Workspace 

The LESSONS workspace contains all of the functions discussed in 
the tutorial APL Is Easy! APL Is Easy! explains APL concq>ts with 
concise, detailed examples. You slKiitM be able to complete the 
tutorial in 10 to IS hours; using LESSONS will help you learn. 

As you woilc through the tutorial, you can verify the accuracy of your 

answers by examining the solutions in LESSONS, or you can copy 
the desired programs into your workspace to save lime. Although all 
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the functions are in die v/&tksipsm y&i Mst create the variables. The 

solutions to the exercises are also in the appendix in the tutorial. The 
DEMOAPL workspace contains the functions mentioned in Chapter 1 
of APLIsEasy! 

9-7 The UTILITY Workspace 

The UTILITY workspace contains a group of functions to display 
nested arrays in iHctcwial form. The primary fimction is DISPLAY. 
It will return a character matrix containing a pictorial represratation of 
the anay provided as its right argument. For example: 

DISPLAY l"l3 



i .— -. . i 

I 111 112! 1123! I 
I I I I I I ^ I I 

I 

DXSPLAY is used exten^vely in Oaptei 1 6tiSmAPL*PWS 
SystemRefermce MamuU. 
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PetfomdVeefips 



To ensure that your APL»H<1^ Syst»n is naming effid^dy: 

use's wrafc^ace td be leadent concun^y. 

' « lll!isO.AIl^ as a shared code segment if you Imv^ 
woddng simultaneously. 

. : , . fhese-two consid^tions are discussed in Sections 10-1 and 10-2, 
req)ectively. 

10-1 Use of Memory 

The size of the APL interpreter itself is approximately 280,000 l^teS. 
The APL worlcspace size can 1)6 increased or decreased using 
r: jCi&#A^;diel£^6st#^aMnabieis 



BowMuehiBoINeed? 

The amount of memory APL uses consists of two parts: a fixed 
■-. m m ttH ^ Kipi es &i^ng B» minimtm sKai^ vmsmry to run AH., and 



a variable amount that depends on how much stcsage you need to use 

for the workspace and full-screen editor. 

The fixed amount is ^proximately 280,000 bytes, the size of the APL 



.1 . = i .1 The variable part of the APL process memory is the dynamic memory 



that APL allocates to use for the workspace and the Session 
Manager/full-screen editor. The amount of memory used 
can be conorolled by APL session parameters. Once APL is running, 
yoa C2U1 cto^ 8^ of the active mnk^jiace tiie system 
command ) CLEAR. For example: 
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at your site. 




mterpreter. 




) CLEAR 500000 
CLEAR VS 



This sets the active workspace size to 500,000 bytes. If the new size 
is larger than the fonner size. APL requests additional memory from 
VMS. 

Eveiy machine has an effective maximum workspace size; requesting 
more woricspace than is available produces an error message: 

)CLEAR 5000000 
INSUFFICIENT SPACE FOR VS 

Section 10-3 contains suggestions on how to proceed if you cannot 
d)tain a workspace as laige as you need. 

Avoiding Excessive Paging 

The size of AFLpMeesses can be a major factor in the effective 
performance d ttie VMS system. The total amount of memory 
allocated to active pioeesses ean be hag^ ttom tfie ttn^ 
memory in the computer. In this situation, VMS pages inactive 
processes to disk, copying them into memory to run them, then 
copying than back to disk. 

Often, the paging (tf tasks to disk has no perceptible effect on APL 
performance. However, when too much process space is allocated at 
once, the machine may begin to "thrash," copying pages between 
memory and disk. The effect can be very frustrating to the APL 
user-the system will appear to freeeze for seconds at a time— and the 
disk drive will be constandy active. 

If you have a problem with thrashing while APL is running, it may 
fael^ to use smaller workspaces or reduce die number of concurrait 
Ail. users. But the problem is most likely to be resolved by 
COOesdting the hardware vendor for advice on whether VMS can be 
"jGWed" to better handle large processes. Often the problem can be 
i^ialyed Minidy by adding more memory, bat tbe hai^bwaie vendw can 
tiest (tetomine how to address your particular situation. 

VMS has excellent virtual memcsy facilities, but as with any such 
systm, performance can suffer if the facility is abused. As a rule, the 
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larger the APL workspace you use, the more your execution 
■ i- 1 . - i! 1. : ■ . ■, . , peformance will be diminished by paging to disk. It is generally wise 

' . to keep workspaces small enough so that they fit completely in real 
memory. 

10-2 Shared Code Segment 

. . ^ .Tn^ig^ectuablefile [APL.RELn]APLXissetuptousea"sharedcode 

' in memory at the same time, no matter how many APL processes are 

running at once. This greatly reduces the amount of main memory 
^ v^igsumedby the APL interpreter, and also makes APL load faster if 

another user is running it already. Each user has his own private 
storage for data and workspace, and there is no danger of one user's 
'■■.W Li conflicting widi anotha. 

The shared code segment technique works only when a central copy of 

■ I' , , V. J -, ; : u the executable interpreter file is used by each user. Making private 

copies of the executable file defeats the braefits of the shared code 

■ v'''i:rtrT»-): .. • ■ ';y;^^; ,j- segment. 

. .. •<^..nam< If multiple users are likely to be running APL at once, the APL 

■u -I - r^- interpreter shotdd be instdled as a scared image pnjgrani.Ij^ only 

one copy of the interpreter resident in memory even if many users are 
, , . rjinning APL simultaneously. The procedure for installing APL in 
. < - vt. . . , : r,^, .Itiisla^on is included in the Installation Guide. 



. , 1Q4 Avomng WS FULL 

There are several possible reasons why you mat not be able to obtain 
'jr*atemii.'r -y; ,v .,7^., v-,., fls4aiK«a woife^ce as you want Allocating the requested amount of 

memory might cause your APL process to exceed the system-wide 
' process size limit (the maximum size of any one process). Or, the 

J xP>-*tdiRwn-;^> , - • total amount ofspace available fn: all VMS processes combined may 

cii *j9:g;£S{ti -iiii ■- beusedjip. 

.3!he.pocess size limit can often be increased by adding memory la flie 
computer and then re-installing or re-configuring VMS. Refer to your 
VAX system administrator's manual or consult with the hardware 
vendor to see if this is possible on your machine. 

Oi^^^im S^SC^huk ;j 10-3 PrafiMinanceTqs 



The total process space can also be increased by reconfiguring VMS to 
provide a lia^ "swap area", the region of the di^ that is reserved for 
storing inactive processes. 

10'4 Monitor Facility 

An important step in improving the performance of your APL 
applications is identifying where the execution bottlenecks. The 
system function DMF monitors an APL function and returns the 
accumulated CPU times for each line of the funtion. When applied 
within an ^plication, it identifies areas of code which may benefit 
from optimization efforts. 

See Chapter 3 of the APL *PLUS R^erence Manual for details on 
how to use UMF. 

MS PmrUta^empOiakm of APL Functions 

This APL*PLUS System uses a technique of partially compiling a 
line of An^ code when it is executed for the first thne. The line is 

translated into an internal form of pseudo-code, which is then executed 
by the interpreter. This pseudo-code differs from the internal form used 
by most Othar AFL systems in that it ddes hot require syneictic 
analysis when it is executed. STSC research has shown that a 
substanial pcHtion of the work done by a traditional APL system is 
sprat in perfiwmfng syntax analy^. 

When a function is first defmed in the system, the input representation 
oi the function (&Skd the Sduice km} is stored in Ae woiiespace 

exactly as typed. The source form is not examined until the first time 
the function is executed, when syntactic analysis is performed and 
pseud^-cdde is genertoed The pseudo-eodeis then stmd ia dte 
function, along with the source code, and is executed the next time the 
function is executed. The pseudo-code needs to be regenerated only if 
the syntactic context on which the function depends has changed. In 
practice this happens only with a change in valence of a user-defined 
object used in the APL statement. 
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Implieaifions of this partial compihttkm inctude: 

• A function runs faster after the first time it has been executed, since 
it neeis syntactic analysis only once. The function also grows to 
orcupy w(»kspace area as die ptseudo-code is generated. 

• When a function is displayed with the Del editor, DVR, or OCR, 
or is edited with the full-screen editor, the display form is the same 
as entered by the user. 

• System functions such as DVR and □ DEF, which maipulate the 
source form of function, are relatively fast 

• Copying a function into the workspace, or redefining it with 
□MF, □V£, cr AeetHiorcaiises the pseud(H»de to be 
Pseudo-code is pieserved in a saved woifcspaGe. 

liiig^ilarly wdl suited fwijqiresaitation in ps«ido-cod^ 

10-6 Multiple References 

The AHL*PLUS System makes CQ^es Of Mi, fables in the 
workspace only when absolutely necessary, 1^ prticular, using a 
variable as the argument to a defined function does not cause an extra 
copy to be made. Also, assignment to one variable of the unmodified 
value of another variable does not cause an extra copy to be made. For 
example: 

A^B'^C'^D-^i IQQ 

creates only one copy of the value (i 100). The value is discarded 
(Mily when the last reference to it is deleted, which occurs when a 
ditfereat valoe has been assigned to each of the variables or whoi all of 
them are erased. 

M^i^ iefeieoces are pmticalarly significant for nested anays. Fot 
Kcamfde: 

il-lOOOpciiooO 
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creates only one copy of the value (l 1 0 0 0). The variable A consists 
of multiple references to the value, not multiple copies of it This can 
yield a substantial space savings in many situations. 

10-7 Dynamic In^Wd Structures 

The data structures used by the APL workspace are all dynamic and 
their sizes can be easily changed. The execution stack (state indicator) 
extends automatically when necessary and releases the extra ^pace when 
it is no longer needed. Thus, the error STACK FULL cannot 
occur, although VS FULL is possible if there is no room to 
extend the stack. Similarly, the symbol table is dynamic, and its size 
can be increased or decreased at any time using )SYMBOLS,eyea 
when names are in use in the workspace. 

Since the symbol table is automatically extended by the system 
yAiSBesva necessary, we recommend beginning your session with only 
a small symbd taUe, piefaably the de&ult of S 12. 



Capyrt^e mf Sm^ file. 



10^6 



^eti^mance Tips 



Glossary 



abort 



Interrupt and aBuidon execution of a {sogiam or a session that is in 
^ ppgiess. 



absolute tab 

, ' . , . A cuTSO' position that is specified relative to the left margin, 
absolote value 



The magnitude of a number, regardless of any negative sign that 
might be presoiL The AFL monadic function I returns the 
absdute value of the number or numbers in its argument 



A matrix associated with each APL component file. The matrix 
consists of three coliunns containing the user account numbers of 
tfiose «4io have been giveti access pertnisif^cm of some ^e, the 
sums of the access codes granted to each user, and the access 
passnumbers (if any) required of each user. 



Wtber 

An integer (ranging from 0 to 32,767) that identifies a user 
account. The user pcMd^ this nuinber to die syst^ at the 
beginning of each APL session. The user account number is the 
value of UAI [ 1 ] . User account numbers appear in the first 
column of file access matrices. 

iMfprmation 



informaticm consisting of the user accHHiHt numb^, the CPU time 

consumed by the APL session, and the elapsed time since the start 
of the APL session. This information is returned by the system 
faaaiaa UAI. 



The workspace that is currently in the computer's CPU memory. 

The last workspace loaded by the user. If the user has just begun 
an APL session, the active workspace is either CLEAR VS or 
a workspace specified as a start-up parameter. 



access matrix 





active workspace 
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address 

An identification that designates a particular location in the 
computer's memory. 

algorithm 

A set of well-defined rules for solving a problem in a finite numb^ 



Alt key 

The shift key for which the red label has been provided. 

ambivalent function 

A function that can take dthra^ one argument (mmadic) or two 
(dyadic). 

APLfUe 

A collection of sequentially numbered APL arrays (called 
components)e stored on disk. APL files are created and 
man^ulated by ^stem fimcticms whose names b^in with OF. 

application program 

A program that enables the computer to perform a specific job. It 
is usually written in a high-level language such as APL, and often 
includes parts written in other languages. 

iirgWB«Bt 

The data on which a function acts. 

array 

An arrangement of elements into zero, one, or more coordinates 



array shape 

See ilbape of an array. 
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■ '■' The acronym for the American Standard Code for Information 

Interchange, used as the standard code for information interchange 
among data processing systems, coramiu^ci^iM SyStrans, and 
associated equipment. It uses a coded character set consisting of 
seven-bit coded characters with an eighth bit available for parity 
. i^eddng. 

assembly language 

:w< -,-T;y. r^.tr- A low-level symbolic programming language, closely lesmbling 

■ . machine-code language, that allows a computer user to write a 
^" program using mnemonics instead of numeric instructions. 

atomic vector 

The vector that contains all of the possible character values in an 
APL system. These chaiactWiEdaes can be letoeoced using the 

tl-M". * ■ ■■JuiiiTi'r 

attention 

An interrupt issued by pressing Bieak while an AH. Stateatn^ (« 
fiinction is being executed. 



attributes 



autorepeat 



The visible, traits associated with displayed characters (colors, 
]^b%htmg, inverse vi^o, blinking, and so on). 



A feature that allows you to hold a key, producing the same lesult 
as pressing the key multiple times. 



badtspace character 

A non-graphic character that causes the cursor to move one 
position to the left Available in APL* PLUS Systems as 



backup 



An extra copy of stored data that can be used in case of accid«ital 
' ^ax^ to or inadvertent erasure of the original (caused by eitfaa* 
:n:<fapman m«r crt maBfaine fiulure). 



Glossary 



baud rate 

The speed of transmitting dma to poiphaals or other computers. 
See also BPS. 



A non-graphic character that produces a bell sound on many ASCII 
(tevices. AvailaUie in AFL*PLUS Sy^ems as UTCBEL. 



binary 



A number rqwesentation sysmn tisbig the base (m&%) two. 

Numbers are written using only the digits 0 and 1 , where each 
additional place to the left represents an increasing power of 2, just 
as in ntHmal decimal ntunbers each |dace nqxesoits an increasing 
power (tf 10, 



bit 



Shortened form of binary digit. The smallest unit of data on 
computers. A single character in a binary number (that is, 0 or 1). 



Uf*pliriBg 



The mapping of the APL characters onto the keys of a bit-pairing 
tominal. Compare to Qrpewriter-pairfaig. 



Boolean 



boot 



Aixays in which all values are either Ofxl. 



See bootstrap. 



bootstrap 



A procedure fix loading a program (asaally the operating system) 
into a con^toras a result of preliminary instructions. This 
procedure is initiated by a switch or by a keyboard input command. 
Also called "IPL." 



BPS 



Abtaeintl^Gii for "yts per second". A measure of data transmission 

speed showing the number of bits of information that pass a given 
point in one second. Bytes per second in ASCII transmissions is 
usually ^>{HOximately BPS divided by 10. 
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,^ ., . branch potential 

" " " The indication of whether an APL statement has terminated with a 

successful branch. One of three potentials associated with an APL 
statement after it has executed. Contrast with display potential 

branch statement 

. , , I,,- A statement inia'^iteed function which changes the order of 

execution of statements in that function. See conditional 
' branch and unconditional branch. 

branch target value 

'' The line number to which a branch is to be made. 

, , , . Break 

. . • .1.- -.r A Signal sent from the keyboard to mdicate that current processmg 

IvJunf ?A " ' '■^ " should be interrupted, or that the line being entered should be 

, p ....... abandoned. It is signaled in this APL* PLUS System with the 

, ' * - Interruptkey. 

Break signal 

The result of pressing Bieik 



' buffer ' 



■ .-I 



A fixed-size internal storage aceadedic^od by the system to a 
particular pifxsi^ Such as holding data received from a port until it 
is used. 



Asequenceof adjacent bits used as a unit of data. One byte usually 
contains 8 bits. 

calling environment 

The environment pma wMiiti a lOnction is call^ ipm to execute 
jmd b wMdi th^ ctaputear letums after its execution. 

canonical representation 

The representation of a given function formed by converting the 
function into a character matrix in which each row is a line of that 
functicn. The explicit result of DCfi. 
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caret 

In an error display, a pointer where the problem was m^unteied. 
Represented by the caret symbol (a). 



catenate 

To join two arrays to form a single larger array. 

character 

Any symbol, letter, digit, or punctuation mark used to control or 



character constant 

A Seri^ of diaiacteis mclosed betwera single quotes. 

character daM 

Data, consisting of symbols (visible ornot) used by the keyboard, 
screen, communications, or printing devices (also known as literal 
data). Each symbol occupies one byte of storage and is found 
mmgii»WSvmip»tiU^ One 
of two datatypes in AH^ Qmltast with numeric data. 

dianacter image 

A representation of a number using the characters 

"0 1 2 3 4 5 6 7 8 . ~" along with its spacing on the page. 

character input mode 

The input mode invdced v/bea □ executes. The system provides 
no distinguishing prompt for the user entry. The result is a 

character vector of the user entry (possibly preceded by a 
program-issued prompt) with no execution or command processing 
ofttieuser ^t^. CliaiacteriiqKit mode is iKHmalty ended by 
pressing Enter, but can be aborted by using the 0-U-T keystroke 
(typically Ctrl-Z). Contrast with evaluated input mode. 

clear worlcspace 

An active workspace created by the ) CLEAR command. It has no 
wori^ieee nameand contains no user-defined functions or 
variaMes. All woikspace-rdaied system varidiles have their default 
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clock 



A device capdde gonoatiiig signals at periodic intervals. 



command 



A word related to a paiticular computer operation that can be used 
alone or with additional information to cause that operation to be 
performed. Most commonly used for the operating system or for 
APL system commands. 

compactimi 

Reclaiming disk storage space abandoned in a component file by 
iq>lacing file components with components of a different size. 

comparison tolerance 

The limit within which two APL values being compared ate judged 
' ' ' " to be close enough to each other to be coiadered equal. The 

amount is controlled by the usea- through DCT. Also referred to as 

"fuzz." 



COmpODNlt 



See file component. 



component file 

See APL file. 

componeni tiiToAnatimi 

Tbe immbers returned by UFRDCI, representing bytes needed to 
component in the workspace, the user account number 
' ' that placed this data in tfie file, and the timestamp (tf when it was 
' placed in the file. 



CQinppnent number 

- ! number used to refer to a file component, including all uses of 

file system ftincdons Urn tetet to in^ifoal eomponefitt 
(OFSMflrnFSf PL>lCf, nFffDCJ). This number is 
assigned to die component when it is first appended by 
WP APPEND. ThemuAbmrisonepeaterdHUitiBttofthe 
component just before it The first c<miponmt app&a6sd to a i^w 
file is numbered 1. 
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compoDDd statement 

Two or more statements written on a single line and separated from 
one another by diamond symbols (0). Compound statements are 
executed in otdex, fiom Mt to right 



computer program 

A set of instructions (called "stat«nents" in AFL) expressed in a 
form suitable for execution by a cranput^. Also caSisd a 
"program." 



qmdiiiwwl branch 

A branch statement whose effect is dependent on some specified 
condition. The agument to a conditional InanchffliQr evaluate to a 
numeric array whose first element is used as flie destination or to 
an empty array, resulting in no branching being done. Contrast 
with unconditional branch. 



conformability 

Tb& reqmKd rank and shape relationship of the array aiguments of a 
function. 



constant 

An array whose content is specified at the point of call (wheie it is 
to be used), rather than referring to another source for the data (such 
as a variable). See character constant, numeric constant, 
varUible. 

contnri idtoracter 

A character produced by pressing a key while hdding down the 

Ctrl-key. 



control key 

The key labeled "Curl." 



conver^OD type 

Specifications for interpreting and storing the data bits read from a 
native file. 
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coordinate 



, .^_cpv 

crash 
CRT 



cursor 



data 



An axis along which data is arranged in an airay, allowing indexing 
(subscripting) selection. To select a single element of data, a 
^iqgle index must be specified for each coordinate. The lengths of 
coradinates ci an amfm given ia the attic's sh^ vector. 



Aamym for C«n»lFtoee®iilg link. The pait of a computer that 
ccmttols tb^^nii^^tation and execution of instrocticms. 



Also called a system crash, is a failure of either the hardware or the 
software. A crash leaves the system in an unusable state. The 
syston inust be re^arted either by ie-booth% fX by pm/edag off 



Acronym for cathode-ray tube. A television-like device used fw 
displaying text and possibly graphic images. 



A shift key (also called control) used to enter control codes from 
the tominal keyboard. For example, Ctrl-S means that the user 
Tresses ibe S key while holding down the Ctrl.fc^. 



The directory that the (q)aating is currently using as the 
default directory. 



Position where the next input or output character will appear on 
die aaceea. BdBcated during input by a blinking undo-lhie oa the 
$cceen. 



, ^A collection of numbers or characters. Datatypes are classified as 
, numeric or character. See character data and numeric data. 
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database 



Data items stored in drdcr lo meet the information processing and 
r^eval needs of an organization. The term implies an integrated 
iBle ot files used by many processing iq;>plicatk}iis as (^pos^ to an 
individual data file for a jKuticular s^ipiication. 



datatype 



See character ddta and numeric data. 



declmat 



decoration 



defanit 



The number representation system using the base (radix) 10. 
Compare to binary and hexadecimal notation. Also, a 
synonym for dedmal pdnt 



An optional modifier used as part (rf Ae 1^ argument to the 
APL * PLUS System function OFMT. Displays the specified text 
with numeric data. 



A value used by a system or language translator when no other 
vaine has beat specified by die nsa or die user's program. 



default disk drive 

"tlie di!^ drive that DOS uses when no (Kdc drive tuts be@> 

specified. The letter representing this disk drive followed by a 
separator character is used as a prompt in IXDS. 



default library 



The libcary used when no library numbo' has been provided. 



defiiult vahie 



A predetermined value used when no explicit choice is made a 
when no explicit action is taken to set the value. 



default width 



Wxstt the widbh qieoificadon of the dyadic format primitive is 0, or 
whoi the widillis unqjecified, the default width is used to format 
the data. The de&ult width is equal to one mcve than the widest 
represoitatoi of any value in any of die eolttmns of the right 
argument whose formatting is contndled by that specification. 
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defined function 

An APL program defined by the user while in definition mode or 
by using QDEF, UDEFL, UFX, or the full-screen editor. A 
' deHned function consists of a header line (that fnrnaUy specifies 
' " - the function name, any arguments, and any result) and lines of 
APL statements. One of three function types in APL. Also called 

and system functimi. See also ftinction. 

iifiB!^''ttBiiie'' 

" ' ' An APL identifier currently being used as the name of a function, 
variable, or label in the workspace. A name that does not produce 



definition mode 

See function definition mode. 



defn error (definition error) 
Aneirarooctti 
fiuiction in Ae nequested. 



With regard to □ FMT, pairs of symbols used to qpeti and close 
text and pattern phrases. 

diam«md symtKol 

''iW^bol 0 used to separate die individual statemoits in a 
conqxmnd statement 

digit 

A gcq^ ehaoK^ dut Rp«sents an ibM^> Goe ti^ 
0 through 9. Also called numeric diaracter. 

digit selectors ^ 

Special characters used in the g format phrase to indicate whoe 
digits in the data are to be displayed. 

dimension 

The number of elements along a single coordinate of an array. The 
maximum size of die number and anangemoit of elcan^its in an 
iBiay. Also called co<nrdinate. See also shape of an array. 
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director; 



System table space used to control data storage and retrieval in a 
file. A table of identifiers and references to the corresponding items 
of {to. Aiso, DOS's table of iafdnnation on a group of files, 
possibly the entire cmients of a disk. 



directory mode 



Amode of ttesiMatt «bere files and workspaces in different 
directories are identified by prefixing the name with the operating 
^stem's diiectcny or path designation. Contrast to Ubrary 
mode. 



dislE 



disk drive 



diskette 



A non-volatile, rotating, data storage devke whose circular surface 
is coated with magnetic material. 



A hardware device that rotates a disk, permitting electromagnetic 
reading and writing of data. 



Synonym f(v a did: (mini-disk). Seedid(. 



display 



A visual piesentatk» of data. 



display potential 

The indication of whether the value of an APL statement is to be 

displayed. If the statement has no value, display potential is 
undefined. One of the three potentials associated with an APL 
statement after it has executed. Oxnpare brandi potential and 
value potential. 



domain 



The set of arguments (or of pairs of arguments) for which a 

function is defined. 



domain error 



An error occurring when a function is executed with one or more 
arguments not in its domain. 
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dyadic function 

A function that lequoes bolb a left and a ri^t aigumenL 

edit 

To add to, eildiigie, or ddete £nxn an existmg progrim w of 

ie^^S^tOrtMA phrases 

Format phrases that convert data in the right argument of DFMT 
into dunacten fa the lesult 

elements 

Theindividaalltnia infln airay. Inanatr^ofchara^datB,eacli 
character is an <3nnent banamqrof nuB>ericdata,eachnunibar 
is an element 



, .. M if An array having one or more dimensions of length zero. The 



number of dMMots in an einpiir aoEdy is zoo. 

empty vector 



Enter 



Ananp^toiaytf one dimension (1 0 or ' '). 



^ key tiiat yoD piess to indi^tts diat yoB itttve finislKd typnig a 

line of input and that the line should now be processed. Called 
"Return" on some computer manufacturers' keyboards. 



A statement or command that cannot be executed, usually due to 
incorrect ooostniction, unaccq)table values, or hardwae constraints 
or failures. 

error handling 

Ibe use (via □ £L X) of preplanned respoises to etrois mXHuitesed 
in statement execution. 



error message 

See error report. 



-1.-- ■ 
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error report 

A message produced by the system wb«i it encounters a statement 
or system command it cannot execute. 



escape diaracter 

A non-printing character, typically with transmission code 27, 
acc^ted % sane odnnmunicating de\^es as a sipiil Hm 
subsequent characters are commands to altra- option settings in the 
device. 

evaluate 

To calculate. See also execute. 

enrinated input mode 

The input mode v/bea □ executes. The system prompt in this 
mode is □ i . User entiy is etndtaied as m APL stetemait whose 
last explicit result is the value used as input. Evaluated input 
mode is normally ended by typing Enter. Evaluated input mode 
on be abaned 1^ ^fNl^^o'' by ewtsi^a bnmefa mow (•*) 
without an aigument Contrast with character input mode. 

execute 

In computer programming, to interpret a computer instruction and 
carry out the (^rations speciOed by the instruction. Also called 
run. Also, an APL fiinction, denoGsd bf the symbol i , that takes 
a character vector or scalar as its argument and evaluates (executes) 
the APL statement represented in the argument. See also 
evaluate. 

execution mode 

Syn(Hiym for inunediate execution mode. 

explicit coordinate 

A coordinate to a primitive function that is specified by enclosing 
it in brackets. For instance, in + \ [ 2 ] /i, the explicit coordinate 
is 2. Contrast with implicit coordinate. 

explicit result 

A value produced as a result of expression evaluation available lor 
use in a^sequNtt e}q)iessions w for screoi display. 
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expon^Mal eiiitbig 

Type of formatting that displays all numbers as multiples of a 
designated power of ten. You specify the number of significant 
, digits to be di^k^ed. 



expression 



Idfeniife^^f^n^ts. atkd/br pdmSiSiwjtm&ikm and qpaauxs in 
syntactic combination. See idso latent expreadon. 



eEtenskm •ai'itr'JX' 

See file extension. 



Tield width 



ffle 



A set of consecutive columns in the result controlled by an editing 
or text format phrase (with QFMT), or a format pair (with dyadic 
TfiEBmat). 



The number of consecutive columns in the result controlled by one 
farmat phrase (with UFMT), or one format pair (with dyadic format). 



A linear collection of related data records arranged m disk in a 
prescribed sequence. Tliensarcan communicate information to, 
and access information from a file using the APL*PLUS PC 
System's rde|^|^m functions. In an APL file, a linear collectiCHi 
of arrays (t^iMelHniPm^). tRa fu^w£lts,aliear i®Qeeitan 
of cWacters (called bytes). See also native file. 



The fundamental storage reference point in an APL* PLUS System 
component file. Any APL array can be stored in a file component. 



file errors 



Errofsjhat occu^Ofing the executim of an instruction that requires 
aiMmBai»^»w6m^^ Mi^beeofioeraMdwi^apMictdar 
M6 or with a disk or disk drive. 



file extension 

The period and zero to three alphanumeric characl^ following the 
name of a DOS file (also known as file type). 
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file identtfication 

The combination of library number and file name (or in the case of 
native files, a library letter, colcm, file name, poiod, itfid optional 
extensi(m) that identifies a file. 

file name 

The name that identifies a file. It consists of one to eight 
alphabetic and numeric characters, beginning with an alphabetic 
chaiacter. 

file operations 

All system functions that query ot alter the files on the dislcs. For 
example, bringing components into the active workspace for 
processing or saving values generated in the active wwkspace as 
componoits of a file. 

file passniunber 

A number appearing in &Awm 3 ^ftfile aoeess maiEix ihatis 
used to control access to the file. Also calted passnumber. 

The space reserved on a disk for filtnre growth of a i»ffticalar API, 
file. Also called file size lunit. 

file size limit 

The size beyond which an APL file is not allowed to grow. Also 
called file reservation. 

file tie 

The arbitrarily established and temporary link that pairs a nutnb^ 

to a particular file so that the number can be used to represent the 
file in the numeric arguments to file system functions. 

file tie number 

A unique number used for referencing a file while it is in active 
use. 

file tie quota 

The maximum numbo' of files that can be tied concurrently. 
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ISee file extension. 



Type of formatting that displays all numbers with the decimal 
point in a fixed position. If necessary, values are padded with zeros 
-'■.•■i-!,:. ; . or rounded to^ceaiply with die numto of dedmal positions 
. - specked. 



A number able to have a fractional part Also, Ae internal storage 
fonnat used for such numbers. 



floppy disk 



A storage medium that consists of a flexible disk (diskette) of 
oxide-coated mylar stored in a paper or plastic envelope. The entile 
envelope is inserted in the disk drive. Also called didtette. See 
also disk. 



format 



fOFinat pafa- 



The primitive function that forms numeric values into a character 
image. In the monadic form of format, the system chooses the 
width and {secision of the image. In the dyadic form , the left 
acguihent icbntrois ttt&^f4Mi and precisicn d the image. 
Represented by the diom symbol (?). Also, to prepare a disk for 
accepting data. 



A pair of numbers in the left argum^ of dyadic thom that control 
the format field wttt ami ^^^ypgei^im whc» totm^^ mt or 
mote cdomns of data in the right argament 



A sequence of characters in the left argument to UFMT that specify 
how a column of data is to be edited or positioned for display 
t^apom. liie^)eiifi«atescontrelihe^ii^,«epe 
precision, and decoration of the di^layed data 



A character vector containing one or more format phrases se^)arated 
by commas that is used as a left argument to QFMT. 
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formatting 

The process of arranging data for display purposes. Formatting 
specifications control the spacing, representation, precision, and 
(Jecotatbn of die displayed data. Also, preparing a disk to accept 

fractional part of a number 

The part of a number to the right of the decimal point. 

ftinction 

A named procedure (program or subroutine) that specifies how a 
job is to be done. A function is classified as primitive (for 
example, +), system (for example, UFREAD), or defined (for 
example, ROVNAMES). See primitive function, defined 
function, and system function. 

function definition 

The rule or algorithm by which a user-defined function is to work. 
A uso'-defined function is entered, edited, and displayed in function 
definition mode or in the full-screen editor. The system functions 
QDEF, UDEFL, and UFX can also define functions. See 
function definition mode. 

Ainction dennition mode 

Backing, modifying, or displaying a defined function using the 
on-screen editing fiacilities. Compare immediate execution 
mode. 

function lieader 

The initial line of a defined function that names the function, 
models and determines its syntax, and names any identifiers that are 
local to the function. Referred to as line [0] when editing or 
using nCRL or UDEFL . 

function line number 

See line number. 

function type 

De^ed functions can either return or not return explicit r^ults. 
They can also be niladic, monadic, or dyadic. Sec also dyadic 
function, monadic function, and niladic function. 
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fiizz 

See comparison tolerance. 

garbage 

Unwanje^dgta^jetnaining from a previous q)eration that has not 
' itamsxy. AhOimyw^mcckaemmi^m, 

garbage collection 

l^ie reanangmoit of the contents of memory that dtaimOBS 
.pwanted data (gaibage) to reclaim 

global definition 

The definition of a functicm or vaiiidile outside of the cuiient (local) 
state of execution. 

global f^yironment 

The collective tenn for the global definitions of all functions, 
variables, and system variables in the active wori^wce. 

global variable 

Witt i^i^e^ Ui a levd of fiincticm ^ecution, any variable not local 
to tbat fimetidn. 

hardware 

. . The physical units making up a computer system (djat is, the 

apparatus as opposed to the software or programs). 



J A function header. 

kisntefiinal notation 

'(feu ^ notation of numbers using the base (radix) sixteen. The ten 
r > .4e(^nal digieO £e> 9 and diekKegts & tbrough F aie esed to 
, . represent the digits Othrougti I5»liesS|>ectively, as single characters. 
One "byte" can be encoded usmg two hexadecimal symbols. 
Ablxeviated^^ called "hoc" 

identifier 

Name of a fiincticm or variable. 
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idle character 

See null character. 



IEEE 



Acronym for the histitute of Electrical and Electronics Engineers. 



imldiffdiaite execution mode 

The method of operation in which any ent£^ statement or system 
command is immediately executed. Inmie<fiafe ^Eeciition mode is 
the initial opoating mode after a user ha$ begun an APL * PLUS 
System session. Also referred to as execution mode. Compare 
with function definition mode. 

implicit coordinate 

A coordinate to a primitive function that is not specified explicitly. 
For instance, in + the implicit coordinate is the last 
coordinate, while in xa, the implicit coordinate is the fust 
coordinate. Compare with explicit coordinate. 



implicit output 



inclusive 



index 



A value iHOduced by an APL expression which is not re-used as an 
argument or assigned to a variable before the ^tonent aids, and 
consequently is displayed. 



Including the numbers at each end of the range as well as the 
numbos between them. 



A mm-negative intego^ used to select an elem^t along a coordinate 
of an array. Also called subscript. 



index origin 



The value that represents the first index position along a 
coordinate. The first number used in counting from the beginning. 
Can be either 0 or 1. Rqnesenu^ by DIO. 



inport 



A source fiom vMch input is received. For example, a serial port, 
keyboard, iOid soeen. 
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input 



input buffer 
input/output 



Data to be processed and instructions to control proc&ssilig eat&c&i 
into the internal storage of a computer system. 



See type-ahead buffer. 



A general term for the equipment used to communicate with a 
computer and the data involved in such ccMmnomcation. 
Abbreviated and also called I/O. 



input source 



kiteger 



Where the input for an APL session is coming firom - usually the 
keyboard, but possibly an APL component file selected by DI^^ to 
act as a surrogate for keyboard input, with each component 
i^tainingone line of input (as built by UCAP, for example). 



A number whose fractional part is zero. In this APL*PLUS 
• I System, an integer can range from "21 47411141 10 

2147483648 and be stored in four bytM. Outside that range, 
integer values are stored in eight bytes. 

faiteger editing 

Type of formatting that displays all numbers as integers. Each number 
riounded necessaiy) itti ^1^^ 

integral part of a number 

The part of a decimal number to tfie Mt of the decimal point 

integrated circuit 

See drip. 



integrity 



iFrotecting daa frtHQ enors in noeiQal ( 
erasure or entering too many digits for a date. 



The number of significant digits provided by the internal 
representation of a number. 
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A computer program that interprets and executes each source 
language siaianeHt befbie inmpe&it^ and executing the ftext 
statement. Often contrasted with a compiler, a program that 
translates an entire source language program into a machine 
language prognun without executing it 



interrupt 



A signal, ccxidition, cr event tbat causes mnmal i»ocesang 
opeiatifflis to be suspoided temporarily. 



I/O 



See inpat/oBtput. 



iMftop 



The upper surface of a key on the k^board and, by exiensicm, the 
symbol or name printed there. 



label 



A name used to identify a line in an APL function. A label, 
followed by a cotmi, immediately pnscedes die rest of die 

statement. Labels are used in branching exfHeSsions as die values 
of the hues on which they appear. 



The symbol n used to separate a comment fiX)m a statement or a 
label A conunoit i»eceded by a n can occupy a sq)arate function 
Biie. 



latent expression 

A system variable (ULX) whose contents are executed immediately 
when a workspace is loaded. Represented by DLX. 



left argument 



The value that appears to the left of a dyadic funcdon. 



length 



The number of positions along a coordinate. See shape of an 
array. 
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library 

, . A set of stored files and/or workspaces. In this APL* PLUS 
System, equivalent to an operating system ^SSSUi^. 



library mode 

A mode of fiie Systran where ffles and ivoilcspaces in Afferent 
directories are identified by prefixing the name with a library 
number. The library numbers are assigned to a directory or paA 
names with DLIBD at a startup parameter. Contrast to 
dire^ry mode. 

library number 

The number used to reference a library, particularly in the 
identification of an APL file or workspace, or in an inquivy 
regarding the contents of a givoi library. 

lineDumber ^ 

In a ftmetiou desMAa, i^weBfyei tiBOdatai a line. 

linefeed character 

A non-graphic chanetCT flat vdhoi displajRd, csnoies 1^ eorSOT 
advance one line, but does not cause any horizontal motion. 
Represented by UTCLF. 

, ^ . , See character data, 

local definition 

- T . \>r :^,P>e definition of a function at a particular state of function 

dennition. If an object's name is not included in the header of 
any function in the state indicator, its local and global definitions 
-~aie the same. 

local environment 

ilie (^fleetive-name for all of the most local d^itions 

functions, variables, and system variables. An APL statement in a 
defmed function can only use or modify the local definitions of 
objects. Comp^ global em^nment. 
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local value 

The value of a variable at a particular state of foncdon execution. 

local variable 

A variable that has a value only during execution of a defined 
function and that is explicitly localized in the function header. 



Ioaiti<ni 



An element of computer memory referred to by its address. 



locked ftmction 

A defined function that cannot be edited or displayed. See also 
ftttetton. 



loop 



A closed sequence oi sMranents performed repeatedly, usually until 
some test condition is met 



l9«r«livel language 

A programming language that is machine-dependent, being 
translated by an assembler into insuuctions and data formats for a 
specific machine. 

low-order digit 

The rightmost (least significant) digit that appears in the 
tefnesenuttion of a number to a given precision. 

machine language 

The set of processing instructions native to the computer hardware, 
and therefore the only instructions the hardware can execute. 
Ccnnmands or instructions in Ugher level languages are translated 
into sometimes lengthy sequMices of machine language by system 
software (such as the operating system command processor) and 
various computer tai^guage pocessm, such as this APL * PLUS 
Systran. 

matrix 

A tecumgular arrangement of elements (numbos or etoaeters). 
Each element requires two subscripts to identify it -- the first 
identifies the row, the second identifies the column. A 
two-coordinate or two- dimensional array, an array of rank two. 
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•■ giHibU'^n Any device or medium capable of accepting and retaining data, so 
-M! : .-. that data can be retrieved and used when needed. Often used more 
' -Narrowly to telet to the computo's intenud memory. 



microsecond ' - ' 

■v^' '°'<^t>x milliondi of a second. 



millisecond 



One tfkidattdith of a second. 



mmus sign 



See subtraction sign and negative sign. 



mnemonic 



modifiers 



A name or symbol chosen to assist tlie liunum monory. For 
example, "fn" for "function." 



A device that permits the transmission of digital signals over 
analog transmission lines. Acronym for modulator-demodulator 
since it modulates and demodidates sig^ials transindaed ovo' 
communication facilities. 



■Jhe clients of format phrases that specify decorations and special 
' ^Efec& with edited data. 



monadic function 

A fimction dutt laikes miy cm data argument (appearing on its 
right). 



most global definition 

The definition of a variable or function at the state where there are 
noj^$|)ended functions (with a clear state indicator). Contrast with 
loiirldRSll^aiid inost local definitkia. 



most local definition 

The deBnition of a variable or function at the current mt6 of 
function «£cuti(xi. 
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native file 



Any operating system file considered as a stream of bytes and 
accessed ««ith file fiincdons beginning with W . Conttast with 
APLfde. 



negative sign 



The sign used to indicate that a number is negative (for example, 
"8). This sign does not indicate an operation. 



newline character 

A non-graphic character that, when displayed, causes the cursor to 
move to the first column In ^ next line. Refiresaited UTCNL. 

niiadic function 

A function that takes no ai;gttments. 

non-^raplik characters 

Characters in the AFL*H.US Symm that, when (i^ayed, do not 
have a visual rqtresentation. 

Numbers zero or highor. 

null character 

A non-graphic character that causes no movement of the cursor, but 
takes the same amount of time as displaying a character. 
VtspaseatBdbyUTCNaL. 



number 



A ^uandty. iTsiltle with arithmi^ functions as addition. 

The more limited set of numbers that can be stored in a computer 
can be expressed as numeric constants. Numbers are left unaltered 
by the APL id^tity function (for examjde, +3), while characters 
are rejected. 



num^ emistant 

A number used directly from the keyboard or within a program, but 
not stored in a variable. It is formed of digits with the possible 
additional use of decimal point, negative sign, or ev^ the letti^ E. 
A number is distinguished from the same character sequence within 

single quotes. 
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numeric data 



A collection of numbers. One of the two datatypes in APL. See 
"ji^ <ittracfer data, elements, number, and numeric 
constant 



= • •, lo. . . 1 .rinji,'-. An organized collection of software that controls the execution of 

computer programs and that can provide scheduling, debugging, 
iiqnit^ENilpateoittlol, accounting, compilation, storage allocatKMI, 
data management, and other related services. The operating system 

r, V) (fnbis-j'1:if\^'. ' ■ I) .1 .2 ■ manages computer resources and provides services to programs. 

• ji'i :>.. -...'Its:*.'' ^j- ..^r fjf-,, . .'i'SBealsosystsDi. 

operator 

M iiA^rimitive function operating on arguments that are themselves 
~ 4 'c -li^imitive functions to create another function. For example, the \ 
>t . ' 'vt^r^.'P k: in ■•■ \ is an operator that combines with the primitive scalar dyadic 
function called addition to produce a pdmitive monadic fimcdrai 
called addiligiHscan. 

wigin 

See index origin. 

origto'depeiident 

Affected by the value of the index (Higin. 

- ' ■' " 'Qiii^ittt/' 

A destinatkn to which output is directed. For example, a serial 
' ' ' ' port, printer* or setie^ 

overstrike 

7 > •• i . . : f, A composite symbol formed by typing two symbols in the same 
cbaiacter position. Also, by extension, symbols that can be 
formed that way even when they have been made available on a 

owner of a file 
' ' llteaccx)^ 

renamed. 
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paraOel port 

A communications channel through which all the data bits a 
byte pass concuirently (instead of consecutively). Typically used 
for impact prxntos. Compare to serial port. 



parameter 

A value specified for use by a program, software package, or 
operating sy^m cimunand, fixxn a limited stt of accq)t^le 
values. 



~ liaasimber 

An integer that can be used to extend the identification of a user. 
Used files to fflcndDse desaUed control over file access as 
i^ified in die access matrix. 



Use of global values for localized system variables that have not 
yet been assigned local values. 

pcndoit function 

A function that is halted because of a suspension in another 
fms&m that is called dib fbncdon. PmSm ftnctions evinot 
be eidil^with function definition mode nor changed (under that 
nait>6) with the full-screen editor. 



po^pherab 

Devices that can be attached to a computer or terminal (for 
example, printers, disk drives, plotters, or miaofkhe viewers). 

port 

A communications channel between a computer and an external 
device such as a keyboard, a j^ter, or a communications line. 



positioning format phrases 

Format phrases (X and 7) that change the appearaiKe of the result 
of UFMT by moving die ciBSor widiout reference to data in die 

right argument. 

precision 

The number oi significant digits used to represent a number. 
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" ""i^- '^''A function built into the APL language and j 
Bon-letter symbol in APL symbol fonn. 



pijliirj^P^ioii 



The system variable QPP that controls the number of significant 



print width 



tlie system variable UPU that control the msJiiBaain ntonl^ of 
character positions or print columns avail^le to the system for 
displaying ouQ)ut 



program 

(To develop) a set of sequenced instructions that cause a computer 
to perfonn particidar opaatioiB, a pian to achieve a isoblem 
solution, or a routine. See also applicadm prognun. 
function, and operating system. 

pr^pitumnied function key 

A key that can be programmed to contain or perform varying 
functions. In the APL ♦PLUS System, the keys fliat can be 
*tM..i -...v. programmed by □Pf'Jrj?!' into multiple charactwsequOTees. 

programining language 

A language designed to express instructions in a form suitable for 
• ; ■ < execution by a computer. Examples are APL, BASIC, COBOL, 
- '<-K)RTRAN, and Assembly language. Also called "compu^ 
progranuning language." 

prompt 

A cue given to the usa by a compalw program asking Ae user to 
enttf information. 



protocoL 

. c.!A se$ of rules and conventions govnning the communications 
b^weeni^ or more devices. Bfxmm^X€ffifWPPmA 
RTS/CTS^ 

polilfecniniient 

A comment at the end of a function line, beginning with R V, and 
retrievable even from a locked function hy UCRLPC. 
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quad functions 

See system functions. 

quad input 

See evaluated input mode. 

quad vmii^cft 

See system variables. 

qimry 

A question directed to the user by a compute progfam, (ff 
vice-versa, to obtain specific information. 

quote quad input 

See cliaracter input mode. 



radix 



RAM 



rank 



read 



reboot 



The base number in a number system. For example, the radix in 
the decimal system is 10. 



An acronym for random access memory. Oftoi, q>ecifically a 

memory chip used with computers that can be read from and 
written on. Contrast with ROM. See also memory. 

Unk 

The link (value of DRL) used by the system's pseudo-random 
numbngmeratn-. 



The number of dimenacns (cooKtoaies) of an may. 



To obtain or intaisetdaia fipom a stoage device, data medium, or 
other source. 



To reload the operating system and reinitialize all of the computer's 
internal memory, as by system reset A final effort to regain 
control of the aunputar without potmii^ oSf and back on. Loses 
all data in compu^ memory. See also bootstrap. 
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action 

-•I'j -<■n^i ici .'^ A function that calls itself during execution, 
renter 

An intern^ c^puter component capable of storing a specified 
amotoit (tf p^N^UBBpie. one wocd). Regist^ hold the results 
of intennediate calculations. 

relatbiadMlllim 

A function used to compare two values that returns a result of 
either 1 or 0 to indicate true or false. See also function. 

reli|tivetab 

A cursor position specified relative to the present position. 

To return components of a computer system to a specified starting 
state. See.^^fvboot 

See field. 

To resaune execution in, and pass a value back to, the calling 
v^nviionment (for example, the results of a function). 

ri^t argument 

The value appearing to the light of a monadic or dyadic function 
name. 

ROM 

Acronym for read-only memory. Typically, a memory chip used 
i >r>i w»{ js^J w3fT rifTl 'f ,s nrtil ■ fi^f;v• i. : -.t ,. wi. ; i . , i v . with compute from which data can be read but to wM^ no data 
;i •. T. . oj f.i!! ;.. '7 v'*''- ' 'f^' can be writtMi. Contrast with RAM. See also memory. 

root directory 

The main directory on a floppy disk or hard disk. 



result field 



return 



■1 V^J 
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row (of a matrix) 

A horizontal line of elements in a matrix or array of elements. 
Also, the first dimension of a two-dimensional array or, more 
goierally, the n^-to-last dimenaon of any array. 



RS-232 

The most common type of connection into a computer for a serial 
device, such as a terminal, modem, or plotter. Its characteristics 
are demmined by a standard from the Electrcmic Industries 
Association. 

nui 

To execute a particular computer program. Also, an execution of a 
pro-am by a computer on a ^ven set of data. Also called 
execoficw. See also eswnte. 



saved workspace 

A Wodcspa^ stored in a lilHaiy (on a di^). 



scalar 



An aiiay of rank zero that must ctmtain a sio^^^ element a 
single number, or a single cfaaiactQT. See also scalar constent 



scalar constant 

A value coded explicidy, rather than being assigned to a variable. 
If numeric, a single number. If character, a single character 
mdosed in quotes. 



scale factor 

For die system function QFKT, the amount by whk;h a number is 
multipli^, expressed as a powo' of 10. 



aeanopmaior 

Primitive £acility that combines with any primitive scalar dyadic 
function to form a new monadic function. The new function forms 

successive elements of its result by using reduction to apply the 
scalar dyadic function to successive take (t) operations of the right 
argument 
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scope 

J !r-;fi . respect to an active State indicator, the collection of 

Oixit^uous environments (function calls) in which a particular 



scroll 



security 



seed value 



serial port 



Uie movement of text oa a CRT (soeoi). 



Limiting access to data based on established criteria (jpayroll 
iafoimation, for example). 



See random link. 



A communications channel through which each data bit passes 
;■!- ' . = r , ,, consecutively. Typically used with terminals. Compare to 

•i ( ... -.1., paralldport 



A period of time during which a particular software system is in 
continuous use. 

isivj'.ty > /.■■.fi«v.j:. .-jt'wiiivi'; > 

.'n- H'. " ' . ' tui-g. s^jsHELirelaled system variables 

•'. i.-: ■ iAi^tem variable whose vs^e is not changed by loading or 

bearing a woricspace. The values remain through an entire session 
unless explicitly changed. Contrast with workspace-related 



shadowed 



. An Al^obfect at a particular state <^ fim(»ion execution dia^ 

inaccessible from the current state because an object with the same 
name is localized at the current state or at an intervening state. See 
scope. 

shape of an array 

» AiQumoic vector whose elements are the dimensmns of Aeanay. 

shared file 

Seefile. 
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shift keys 

K^s that aivsr the effect of pressing a characta key. 



sl^ifkant digits 

Those digits in a number which can be trusted not to have been 
distorted or rendered inaccurate by measurement, calculation, or the 
storage fonnat. 



singleton 



An array containing a single number or chatactn' regardless of rank. 
Any elements in its shape vector are 1 . 



siDkffle 



A file into which materia destined for display on ^ screen is 
placed, either in ad^on to or in plaoe of du» sao&eu 



software 



Asetoffttnetions,] 
operation of a computer system. See also hardware and 
program. 



the 



spool 



Acronym for simultaneous peripheral operations on-line. To write 
or read data to or fam f&^^heM devices concurrraitly with 

execution of another program. For example, to spool data ready for 
printing so that it is printed while the computer is freed for other 



state indicator 



statement 



A t^ie in tlie active w(^eq)ace tint tta^ tfe ^cetmtion progress 
of d^ned functions. If function execution is halted, the state 
indicator shows the halted defmed functions in order (the most 
recently active suspended function first) and the line in each 
function whoe execution sopped. 



A syntactically well-formed expression of APL primitive functions 
and operators, data constants, variables, and user-defined functions. 



statement label 



See label 
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stetusUne 
Steward 

The individual or user account number that can add, delete, or 
; - t..y-}(^r » t,:^ modify the access of other user account niunbeis to a particular 
' ' 'sd^bvareapidicatioa. 



stopping 



store 



The use of the system function □ STOP to cause function 
Qcecuticn to halt befne esxecuting specified fiincticxi lines. 



To enter data into or retain data in a device from which it can be 
retrieved at a later time. 

strong interrupt 

-r.; - '-'^'^f^ or more Breaks entered in quick succession during processing. 
A strong intranqK is recognized during the execution of an APL 
statement, a^l^y halt execution before the entire statement has 
completed. Coottast with weak interrupt. 



' sobpro^ram 



subroMiiie 



Synonym for subroutine. 

A subsidiary routine called the main ivogram. Alsooilled 



sflb^^Hpt 



The value used to indicate the specific position(s) along a given 
coordinate of an array. Also called index. 



'" ' ' - ' The sign used to indicate that the subtraction function is to be 
poformed (fat example, 5 - 3), rqifesoited by the hyphen. 

"' ' suspended function 

i. .li 1 . .. ^ function whose execution has been halted at some point because 
of an enw, a Bre^ signal, or a Stop set by □ 5 r 0 f . Suspended 
functkmssKemiB^&tfesGilBini^torl^a *. Seestate 
faidicator. 
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suspended workspace 

A workspace whose state indicator is not empty. 



symbol table 



syntax 



syntax error 



The area of a workspace that stores the names of APL objects that 
have beoi rdfened to in the wcnkqxice. 



In APL, the rules by which functions and dieir airgaments are put 
together to foim valid statements. 



An error occurring £tom an improperly fcnmulated expression or an 
improperly called function. This may be caused, for example, by 
unmatched parentheses, by two variables juxtaposed with no 
function between them, or by a function used without correct 
argumdots specified in die fimetion header. 



system 

The ^ysiod equipment and software used as a unit to process data. 

A system includes the central processing unit, its operating 
system, and the peripheral devices and programs under its control. 

systm command 

An instruction used to direct the APL*PLUS System in 
pofonning certain housekeeping ta^. An instruction that allows 

the user to monitor and control the contents of workspaces, files, 
and libraries. Every system command begins with a " a ". System 
commands capnot be used as part of an AFL statement or defined 
function. 



qrstem con^ant 

A constant value available from the system (like a systrai 
variable), but one that is not user-definable. 

system functions 

A special class of functions that can always be used from the active 
workspace. They occupy no storage in the workspace and do not 
appear in the ) FNS list. System functions have names beginning 

fte quad symbol (□}. Some system functions perform 
operations similar to system commands. 
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systeoi status line 

- ' A lineatthebottom of^srae^ ttrnt^i^s ffie^^ 

of such items as workspace idratificatitm, k^board stales, and 
printer activity. 

^tettt «UFiiibles 

A special class of variables, always in the workspace, that are used 
tonKmitororcontndtfietmMlciq)a^cffsesd«tt^e^ Th^ 
aie^slingaished by having names that begin with die quad symbol 
' -(□). See workspace-related system variables and 
sessioD«related system variablM. 

text format phrases 

Fonnat phrases that insert characters into the result of UFHT 
viidiout referencing data in the right argument 



1^^tes»rtkfn 



Type of formatting used to insert specified text directly into the 



thorn symbol 



tie 



the f itsid 10 r^aii^mt the fonnat fvimitive function. 



whoi it is in active use. Also; ifae nrntch of fiks to tie number so 



tie number 



tied file 



See file tie number. 



A file currently paired with a number (its tie number), and 
consequently available for processing. Currently tied files can be 
listed by UFNAMES 0 DNNAMES. See also tie number. 



timestamp 



A record of the date and time that some event occurred (for 
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tracing 

The use of the system function UTRACE to display the result of 
sfatemoits m specified lines. 

translation 

A diatacter-l^-cteK^ substitution to adjust for prqper printing or 
for uaiBmission to a device inoqpable of dealing mUh the original 
form. 

•translaiyKan table 

An array of characters indexed by subscripts into a character set in 
oidarto map characters from one character set into a different 
chaiactO' set. Such a table might be used to map ASCII character 
codes to corresponding internal APL characters, for example. 

^jrpe-ahead buffer 

An area in memwy where typed keystrokes are collected until the 
syston is ready to process duan. 

typewriter-pairing 

A mapping of the APL characters onto the keys of a 
typewriter-pairing terminal. Compare to bit-pairing. 

unbalanced quotes 

An odd number of quotes (not counting any quotes in the optional 
commoit) in an APL siatmenL 

unconditional branch 

A branch statement whose effect is always die Siune. Contrast 
widi GMditiraal branch. 

user account nmiber 

The unique integer used by an APL ♦PLUS System to identify a 
user. The user account number is the value of IIUAV. 

nser-defined function 

See defined function. 

Data that can be assigned to a variable, specific data (either a 
constant, the contents of a variable or system variable), or the 
explicit result returned by a function. 
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. yalji<e potential 

. ' I •! /.-i!f!»ii ;f: ; The indication of whether an APL statement returned a value. One 
of the three potentials associated with an APL statement after it has 
executed. Compare branch potential and display potential. 



A named collection of data or a named array. 



A linearly arranged array, an array with one coordinate (dimension), 
an array of rank one, or a data structure that permits the location of 
any item by the use of a single index or subscript. See also 
atomie vector mi empty vectw. 



video attributjcss 

-1 See attributes. 

visual representation 



trailing dd symbols (V) and line numbers. Hie result of OVA. 

waiting function 

A function called in the currently executing APL statement whose 
left argument is being evaluated prior to beginning the functioa. 

weak interrupt 

A single Break entered at the keyboard. A weak intmupt is 
recognized only at the completion of a line of a fimction. Contfast 
. . . with strong interrupt. 

window 

A rectangular ^dion of the CRT screen, specified by four integers, 
r ' The first two niisg^ re|>resent the locadicm on tte^^si^ 

upper-left comer of the window. The second two integers represent 
the shape of the window (rows and columns). 

window specification 

A precise description of a particular window, given as an integer 
vect^ wiose four elements n^pti^t tibe SQu^ imt mi &skiim 
(the positicm of the iqipa-teft cotaex) and the size of die window. 
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^rorkspace 

The APL execution environment in which computation takes place 
and in which names have meaning. A wortcspace contains the 
variables, defined functions, and control information for an APL 
session. A repository for a collection of functions and data. 
Woriopaces can be stored in litKariesfcH* later use. Seealso 
active worfcqiace and saved workqiace. 



inrkqMce identiffcatioa 

Tlie library number and wrakqnce name dut idoitify a wodcspace. 



workqMcei 

A sequoice of one to eight characters, all of which must be coital 
letters or digits and the first of which must be a lett». 



workspace parameter 

See system variables. 



irarkqMce-related system variables 

System variables associated only with a workspace. Their value is 
not preserved when another woikspace is cleared or loaded, or when an 
APL session ends. See also session-related system variables. 



To continae imintenupted on a second line of the screen a line 
begun above. 



mrap marker 

Hie screen attribute used in the letiSBm cobmm itf (he emtm. 
window to indicate that the line on whidi the maiker occurs is part 
of a wrapped line begun above. 



e 



A line on a CRT screen that is longer than the width of the screen. 
Hie ^Dai^y of a wrapped line occif^ took than one physical line 
on the screen <x continues on die line or lines bdow its beginning. 
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a 
a. 



System Chcmcteristics and Limits 




im ir The characteristics and limits Ais APL*PLUS Syst^ are listed 

■ • below. 

The character set is described in Ai^)endix B of this Manual. 

awing internal data npesmations ate used: 

one bit per element (range 0 - 1 ) 

32-bit 2's complement integers (range 
-2147483648 to 2147483637) 

• Floatingpoint 64-bit VAX-D format double precision 
(range: negattvertmnte'limitio 
positive-numb^-limit) 

*'(3atkii^ 8-tHtdiaractQrs 

• Nested four-bytes per element at outermost level 
(4-byiepointa-) 

• Heterogeneous 10 bytes per elemOTt (one byte datatype, one 
byte reserved, eight bytes to hold latgest 
possible value). 

In the following table, when a limit is given as "none," that there is 
no constant value that the system enforces as a Umit. Available 
woikspace area is the <nly liniitato that applies in diese cases. 
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System Charactofistics and limits 



Positive-namber-limit: 
Negative-number-limit: 
Positive-counting -number-limit: 
Negative-counting-number-limit: 
(Coordinate-length-limit) Index-limit: 
Length-limit: 
Rank-limit: 
Identifier-length-limit: 
Quote-quad-output-limit: 
Compaiison-tolerance-limit: 
Integer-tolerance: 
Print-precision-limit: 
Full-print-precision: 
Exponent- width-limit: 
Indent-prompt: 
Quad-'prompt: 
Function-definition-prompt: 
Line-limit: 
Elements-per-array-limit: 
Piinting-width-limit: 
Symbols-limit: 
Input-line-length-limit: 
Function-line-length-limit: 
Execute-arg:ument-lengili-liinit: 



1 . 0141 1834$04iS229f 31 
- 1 . 0 1 4 1 1 8 3 4 60 4 6 9 2 2 9 £■ 3 8 

72057594037927936 ( "1+2*56) 
"72057594037927936 (--1*2*56) 
2147483647 
2147483647 
127 
100 
none 
1£-13 
2*-32 
1 8 
1 8 
3 

6p' • 

'Ds • .QfCITL.ep' • 

' 1234567890. [3 ' 

32767 

2147483647 

255 

32767 

1014 

none 

2147483647 
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System Character Set 



The following table describes the characters that make up the 
Atomic Vector (DAY) for this APL*PLUS System. The table 
includes: 

• decimal index in Dj^V^ (origin 0) 

• display fonm of die character 

• the ova^t^ sequence (if any) diat can be used to oeate die 

• diB^harac^snanie 

H 

> die fearminal required. 

Your terminals may not be able to display all of the characters 
d»x»£edh^. G^SFEdly, dds^mpli^ character set is ai^iabte 
only on bit-mapped devices in which a custom font has been 
developed or on personal computers used as terminals in which the 
Mlware has be^ eMM^^ # iljpOft APL (widi a ROM or 
do^dteia^Ie^haracta' sei0. 

Chaiacteis tfi|t require a s^tsM tsmiml (odier dian an ASCn 
tenainaO are lUtgged with die following codes: 

APL ' An AEL terminal is required to di^lay this charact^. 

extended A terminal widi an extended character set and a 
custom font that includes diis special character is 
reipied. 
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Index Chair OnarsbHee 



0. 






1. 


A 


ou 


2. 




/ _ 


3. 




€ _ 


4. 






5. 






6. 


4- 




7. 






8. 






9. 






10. 






11. 


C 




12. 






1 o. 






1 A 






1 

± o. 




* o 


1 e 






1 7 






1 8. 


1 


I _ 


19. 




V 


20. 


u 




21. 


I 


1 T 


22. 




0 


23. 






24. 


t 




25. 


^ 




26. 


-» 




27. 






28. 


H 




29. 


1- 




30. 




A 1 


31. 


t 


V 1 


32. 






33. 


1 


1 


34. 


II 




35. 


# 




36. 






37. 


% 




38. 


& 





Name 


Terminal 


n T> y 1 r r r T 

UTCNUL 




smiling face 


Extended 


inequivalent 


Extended 


qps^on-undersaxe 


Extended 


(fiamond 


APL 


dieresis 


APL 


left aiiow 


APL 


QTCBEL 




UTCBS 




horizontal tab 




QTCLF 




implication 


AFL 


n ^ 

BTCFF 




UTCNL 




reverse implication 


APL 


logarithm 


ArL 




BXKSluXO 


sandwich 


Extended 


iota-underscoie 


Extended 


uel-tilde 


APL 


low^-case u grave 


Extended 


I-beam 


APL 


zUde 


Extended 


omega 


APL 


take 


APL 


J 

drop 


APL 


right arrow 


AM. 


DTCESC 




ifgiitta^ 


APL 


left tack 


APL 


upgrade 


APL 


(kjwngrade 


APL 


space 




shriek 




double quote 




number sign 




dollar sign 




pm%ntsign 




ampersand 
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39. 


1 


:. 


single quote 




40. 


( 




leift parenthesis 




41. 


) 


Q 1 s> 


right parenthesis 


: 


42. 


★ 




power 




43. 


+ 




plus sign 




44. 






comma 




45. 


- 




minus sign 


■ • - ■ ■ 7 ^ ! 


46. 


. 


J •? 


period 




47. 


/ 




slash 


"1 


48. 


0 




zero 




49. 


1 


■ 


Mie 




50. 


2 


• ■ <■ 


two 




51. 


3 


' ^ 


three 


1 • - 


52. 


4 




four 




53. 


5 




five 




54. 


6 




six 




55. 


7 




seven 


•> II 


56. 


8 


C - 


eight 




57. 


9 








58. 






colon 




59. 






semi-colon 


.1 


60. 


< 




less than 


r !vu:.> »i.vf,' 


61. 






equal 




62. 


> 




greater than 


- ,- -■ T* " .1 


63. 


? 


^ . ; 


quay 




64. 






at-sign 




65. 


A 




iqjper-caseA 




66. 


B 




tqjpo'-caseB 




67. 


C 




upper-case C 




68. 


D 




iQ)per-caseD 




69. 


E 




upper-case E 




70. 


F 


• : 


upper-case F 




71. 


G 


; 


upper-case G 




72. 


H 




vppet'Gmli 




73. 


I 




upper-case I 




74. 


J 




uH)er-case J 




75. 


K 




upper-case K 




76. 


L 


I f 


upper-case L 




77. 


M 




upper-case M 




78. 


N 




iqjper-caseN 
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Terminal 



79. 


0 




upper-case 0 


80. 


P 




upper-case P 


81. 


Q 






82. 


R 




upper-case R 


83. 


S 




upper-case S 


84. 


T 




upper-case T 


85. 


U 




upper-case U 


86. 


V 




upper-case V 


87. 


V 




ippCT-case W 


88. 


X 




upper-case X 


89. 


Y 




upper-case Y 


90. 


z 




upper-case Z 


91. 


L 




leftisacket 


92. 


\ 




backslash 


93. 


] 




right bracket 


94. 


A 




logical and 


95. 







undeiscttc 


96. 






left single quote 


97. 


a 


A. 


lower-case a 


98. 


b 




lower-case b 


99. 


c 


C_ 


lower-case c 


100. 


d 


D_ 


lower-cased 


101. 


e 


£_ 


lowCT-casee 


102. 


/ 


F_ 


lower-case f 


103. 


9 


G_ 


lower-case g 


104. 


h 


H_ 


lower-case h 


105. 


i 


I_ 


lower-case i 


106. 


J 


J_ 


lower-case j 


107. 


k 


K_ 


lower-case k 


108. 


1 


L_ 


lower-case 1 


109. 


m 


Af_ 


lower-case m 


110. 


n 




lower-case n 


111. 


0 


0_ 


lower-case o 


112. 


p 


P_ 


lower-case p 


113. 


g 


Q- 


lower-case q 


114. 


r 


R- 


lower-case r 


115. 


s 


S_ 


lower-case s 


116. 


t 


r_ 


lower-case t 


117. 


u 


i/_ 


lowo'-case u 


118. 


V 


v_ 


lower-case v 
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Terminal 





119. 


IT 


V_ 


lower-case w 






i20. 


>r 


X _ 


lower>ciisex 






121. 


y 


y _ 


lower-case y 






122. 


2 


z_ 


lower-case z 






123. 


f 










124. 


1 
1 




split stile 








1 
/ 




ngni DFaCC 










.-.•if' 








127. 






UTCDEL 






128. 


c 

« 




upper-case C cedilla 


Extended 










lower-case u umlaut 






1 ^ n 










■-;■> .■■;.:-n-^ 


1 O 1. 


3 
a 




iOWCr-CoaC a CUCUniliCA 






1 Q 9 


Jt 
a 








10 0. 








pYtpnHpH 




1 Q il 




. . . , 


n^vC* Am vol 

c^uau 


APT 


135 ' 

X w w ■ 






Icrsfsfest-csssR C ceiffllai 






136. 


§ 




lower-case e circumflex 






137. 


e 


- . 

- ( ^ ! 


low^-case e umlaut 






1 3S 

JL «9 w« 


& 


.1 








139 


if 


S .' ■ 


fomMR^racg j Mrnlaut 


Extended 




1 4 n 
1 ^ u . 


t 
1 






pYtpnHpH 




14 1. 


r 
1 




ceiling 


AT>T 






/\ 




i^ier-csw A umiaUt 






1 4 0 . 


1 

L 




floor 


APT 




\ A. A. 


t 




IlT*r*Pr-/^!lC/» P QT51V(* 


pYtpnHpH 




14 9. 


A 




iieiCa 


APT 




X *x D . 


X 






APL 




14/. 


?< 

u 








.' "jA. '.,f..> -«'--i.'r:" 


'4 JL 


w 




lUWCr-CoaC \J lUIiKtUl 


EumCmKwU 




14 3. 


n 

u 






APT 




1 'iO 


Q 




lnwpr-rfl<i£* ii rimimflpx 


Fxtended 




151. 


□ 






API 




152. 






domino 


APL 


) ■ 


153. 


0 




upper-case 0 umlaut 


Extoided 




154. 


0 




upper-case U otnlaut 


Extni^ 




155. 




c 1 


cent sign 


Extended 




156. 


£ 


{ 1 


British pound 


Extended 
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Name 


Terminal 


157. 


¥ 


Y- 


Japanese yai 


Extnided 


158. 


7 


~ 1 


catbar 


Extended 


159. 






frown 


Extencted 


160. 




a / 


lower-case a acute 


Extended 


161. 


1 


i / 


lower-case i acute 


Extended 


162. 


6 


0 / 


lower-case o acute 


Extended 


163. 


0 


u/ 


lower-case uaeute 


Extended 


164. 


n 




lower-case n tilde 


Extended 


165. 






upper-case N tilde 


Extended 


166. 


n 


n • 


comment lamp 


APL 


167. 




\ - 


backslash-bar 


APL 


168. 


i 




inverted query 




169. 


D 


[ ] 


squad 


Extended 


170. 


T 


T " 


aiout 


Extended 


171. 


V 




fitog 


Eidended 


172. 




* " 


sourpuss 


BfOeaded 


173. 


i 




inverted shriek 


Extended 


174. 


« 




left guillemet 


Extended 


175. 


» 




right guillemet 


Extended 


176. 


8 




.25 shading character 


Extended 


177. 


1 




.50 shading character 


Extended 


178. 


1 




.75 shading character 


Extended 


179. 


1 




Uoe-towing diacacter 


Eiaeaded 


180. 


H 




line-drawing character 


Extended 


181. 


H 




line-drawing character 


Extended 


182. 


i 




line-drawing charact^ 


Extended 


183. 


1 




line-drawing character 


Extended 


184. 






line-drawing character 


Extended 


185. 


■a 




line-drawing charted 


Extoided 


186. 


1 




line-drawing character 


Extended 


187. 






line-drawing character 


Extended 


188. 






line-drawing character 


Extended 


189. 






line-drawing characto' 


Extended 


190. 






line-drawing character 


Extended 


191. 






line-drawing character 


Extended 


192. 


L 




line-<bawiAg dwaeta* 


Extended 


193. 


J. 




line-drawing character 


Extended 
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194. 


1 




line-drawing character 


Extended 






195. 


I- 

1 




line-drawing character 


Extended 






196. 






line-drawing charact^ 


Extended 




' • ■ . 


197. 


T 




line-diawing character 


Extended 




. ■■ • : . 


198. 


r 




line-drawing character 


Extended 






199 


1 

r 






Extended 


1- * / 




200. 


B: 




line-drawing character 


Extended 


-J'; - 




20 1. 


B 
I 




line-drawing character 


Extended 






b V/ 




t, 


HH&iflfawiiig charsicter 


Extendi 


■'■ 




203. 


If 




line-drawinc character 


Extended 






£■ V ^ ■ 




■ - ^ 


line-drawinff character 


Rxtended 






205 

b V/ O ■ 






line-drawin? char^ter 


Extended 








T 




linp-drftwin? f^svx^PT 


FxtendM] 






207. 






line-drawing character 


Extended 






208. 


X 




line-drawing character 


Extended 






209 


T 












210. 


TP 

n 




line-drawing character 


Extended 






211. 


IL 




line-drawing character 


Extmded 


) /. 




212. 




• ^1 - 






- • " r - 




213. 


p 




line-drawing character 


Extended 






214. 


1 




lilKHteiwu^ cjhar^tsr 


Extended 




215. 


4 












216. 


T 




line-drawing charade 








217. 


J 




line-drawing character 


Extended 






218. 


1 




line-drawing character 


Extended 






219. 


1 

■ 




solid chfflactef 


Extended 








■ 




crvliH Inu/pr-hiilf rhjimf^tpr 










1 
1 




solid left-half character 


Exli^ided 






o o o 


■ 
1 




solid ri^t^half chaiaciif 








0. 


■ 




soiia uppec *naii cnaracier 


Extended 






224. 


a 






APL 






o o c 

22 5. 


s 




uerman double-o 


Extended 






226. 


I 




iota 


APL 






227. 


b 


• ** 


hoot 


Extended 






228. 




o " 


holler 


Extended 






229. 


V 


V ~ 


nor 


APL 






230. 


1 




base, decode 


APL 
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23 1. 


T 




encode 


APL 


232. 


<D 


o 1 


rotate 


APL 


233. 


9 


o - 


lotate-bar 


APL 


234. 






nand 


APL 


235. 


/ 


/ - 


slash-bar 


APL 


236. 


V 




del 


APL 


237. 




o \ 


transpose 


APL 


23 8. 


€ 




epsilon 


APL 


239. 


n 




intersection 


APL 


240. 






eqpiivalent 


APL 


241. 


A 


A _ 


delta-undersoHe 


APL 


242. 


t 




greater than or equal 


APL 


243. 


i 




less than or equal 


APL 


244. 


f 


T • 


thorn 


APL 


245. 




I • 


hydrant 


APL 


246. 


T 




divide 


APL 


247. 


If 


n 

• 


Goman QpetHpiote 


Extended 


248. 


0 




jot 


APL 


249. 


o 




circle 


APL 


250. 


V 




or 


APL 


251. 


p 




rho 


APL 


252. 


u 




union 


APL 


253. 






high minus 


APL 


254. 


1 




stile 


APL 


255. 






undefined 
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Error M€smges 



This chapter contains the error messages displayed by the system along with the 
probable cause of the error. Detailed explanation of the cause of an error may also 
be found in the destSi}Mioii~tf die fuiK»km or sy^^ 
enor. 



Error 

AXIS ERROR 



DISK ERROR 



DOMAZn ERROR 



FILE ACCESS EMROR 



Explanation 

An attempt has been made to select a 
non-existent or invalid axis 
(coordinate) of an anay fcv use with a 
fimc&n (V dpetator. 

A VMS ^!^em file operation used 
biteffli^ by AFLhas prodUGed an 

unexpected error. In most cases, the 
error message will include the VMS 
reboncode. 

The argument supfdM ismdie 
right type or has a value ouG^ the 
accqp^le range. 

You are not permitted to access this 
file, or the supplied passnumber is 
inctmecL 



FILE ARGUMENT ERROR 



FILE DAMAGED 



The file name is incorrect. This often 
arises finxn using a directory name 
while the system is in library mode or 
a library number when in directory 
mode. 

Internal inconsistencies have been 
found in an APL component file. 
This can be caused by writing to a 
component file with native fUe 
opeiaskm. 
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Error 

FILM DATA ERROR 

FILE FULL 

FILE INDEX ERROR 

FILE NAME ERROR 
FILE NAME TABLE FULL 

FILE NOT FOUND 

FILE TIE ERROR 
FILE TIE QUOTA EXCEEDED 

FILE TIED 



Ebcplanation 

The file component does not contain a 
well-fonned APL array. The 
compomant was inx)bably writlea by a 
non-AFL jmgfaxa. 

lbs ^»ce required for this operatic 
would cause die file to exceed its size 
liniiL 

The component number lies outside 
Ae range of valid component numbers 
for this file. 

A file with the same identification 
(flam) already easts. 

Thoe is insufilciait spce available in 
the internal table used to cmtian file 
names. 

The file was not found in the library 
or directory specified (may be the 
ddfaiilt wc^^ diie^f^ if m W^my 
number or direcfeory name is 
supplied). 

No file is tied to the tie number 
supplied. 

There is a maximum number of files 
that can be tied at one time. This 
operation would have exceeded this 
limiL 

Another user already has tte file 
exclusively tied. 
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E^mnr 

FORMAT ERROR 

MOST MCM$$ MMOM 

INDEX ERROR 
INCOMPATIBLE VS 



IHCORRECT COMMMD 



INSUFFICIENT MEMORY 

- INSUFFICIENT PROCESS 

SPACE 



. . ;. , . - -LENGTH ERROR 



ExplaaafioB 

The format phrase provided to QFMT 
is ill-formed. Up to 16 characters of 
the incorrect phrase is displayed 
preceding lt»POMMAf ERROR 
phase. 

The operating system^ ffle 
permissions on this native file do not 
permit the file operation (see 
ONRDAC). 

The index is not in the range of valid 
indices fx diis v^oiable (died^ UIO). 

The specified workspace was saved by 
a newer version of AH. Aan the one 
you are using. 

The system command is ill-formed. 
Some possible causes include: 
< AiA&pSQiideMMnd 

• A librarj' TsaB^b& has been used 
when the sysfisnis in directory 
mode 

• Mscellaneous and extraneous 
matmal following the command 

• The atgum^it supplied is invalid 

There is not enough system memory 
available to complete the qpeiation. 

Workspace size required for this 
operation would cause the APL 
process to exceed the cqmting 
system's configmadon limit. 

The argument does not have the 
conect shape. For example, it 
supplies five numbes^ v/hen it should 
su{^ly only four. 



Error 

LIBRARY NOT FOUHD 
LIMIT ERROR 
NO SPACE FOR UDM 
NONCE ERROR 

NOT COPIED: 

NOT COPIED, VS DAMAGED 

NOT WRAiEJit 

NOT FOUND: 

NOT IN DEFN OR QUAD 



l^liEination 

The specified APL library number is 
not defined in QLIBS^ ox the 
directory refer^ced does not exist. 

The number is out of the accept^le 
range of numbers or some other 
system linut has been reached. 

Tbete is notraough space in the 
wodc^ace to record the diagnostic 
fl^ssafe. 

The supplied argument follows the 
design principles of the system, but 
for various implementation 
considerations is not valid in this 
version of the system. 

The indicated objects were not copied 
from the saved workspace because the 
active workspace is full, the symbol 
table is full, or the saved wodc^ce is 
damaged. 

The copy operation could not be 
compleied becat^ flie ^ed 
woikq>ace is damped. 

The requested objects not ^ased 
from the workspace because they were 
pendent or suspended. 

The indicated objects were not found 
in the saved workspace. 

This system command is not 
permitted while the system is in 
Q»input or function definition mode. 
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Error 

RANK ERROR 

SYNTAX ERROR 
SYSTEM ERROR 

VALUE ERROR 

VS AnmUMNf ERROR 

VS DAMAGED 

VS FULL 

VS NAME ERROR 
VS NOT FOUND 

VS TOO LARGE 



ExplanatloB 

The argument supplied is of inconect 

rank. For example, a matrix was 
supplied wtien the system was 
eas^«e6ng & vector era xtOiat. 

The statement supplied is not a valid 
AFLstatemrat 

An error has occured in the APL 
intapieter code, possibly caused by 
damage to the workspace's internal 
data siractures. The APL session is 
tcnnioaied after a S3fstmi end. 

The object identifier (name) does not 
have a value in this wodcspace. 

The wodispaee klenttlar is iU-fonned 
or is too long to pfocess. 

The soiin% wiHlg^age 18 not in the 
correct form for a saved wodc^pace, or 
adisk enor has occurred. 

This operation requires more 
workspace than currently available. 
) CLfA£ can be used to oiliuge the 
woriE^Bce. 

A workspace already eusts with die 
name siq)plied. 

The workspace does not exist in the 
specified directory or you do not have 
permisdcHi to access it. 

The saved workspace is too large to 
be used at Ais time. 
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This APL*PLUS System for the VAX/VMS environment emulates 
the UNIX operaUng, system's "termcap" (teoninal cacabili^) facility as 



toninals. A termcap file is a database that describes the control 
sentences apivopriate to a large number of different screen teiminals. 

A small termcap database that describes popular APL terminals (the 
atermcap file) is included with the APL*PLUS System. This 
appeaSix. provides the material you need Id add other terminals to the 
termcap database by augumenting the atermcap file. Experience 
with the UNIX termcap facility is most useful in modifying the 
atermcap file. In f^t, adding a UNIX termcap entry into 
atermcap is the quickest way to provide some terminal support for a 
new terminal since the termcap databases distributed with UNDC 
^slems often contain entries for a large number of terminals and 
many terminal manufacturas will provide a recommended termc^ 
entry a tetnuflal fpiA injoest. 

Customization of the UNIX termcap eiMy will likely still be needed to 
fiilly utilize all die feautes ^ wiiA a new vste^snsL ff you aie 
unable to locate a termcap entry that works with your terminal, contact 
our Help Line since we may be able to supply one or help you 
oaaswMaimiatymum^a^ The t^honenumbor for our Help 
Line Qifi be found at the end (tf die Introduction. 



In order to jrovide full-screen support lor your terminal, APL needs 
two e^^fiiial pieces of infinuttion: 

• the type of terminal you are using 

• dK lfiime of the tennc^ database to be used. 




Identifying the TthKbuAmi Termcap to APL 
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The tenninal type is determined from the value of the terminal= 
startup parametra:. 

$apl terminal=vtlOO 

The tamcsp file is identified by the temcap- stattap parameter. 

Custom Termeap 

The file atermcap that is distributed with flie AFt*PLUS System 
is a termeap file that describes most popular APL terminals. The 
following table lists the termeap entries used by the APL* PLUS 
Systran. 

Termeap Entries Used by the APL * PLUS System 



Name 


Use 


ti 


Cursor movemoit initialiaition strbig 


te 


Cursor movemoit de-initiatization string 


sr 


Scroll reverse 


up 


Move cursor up 


do 


Move cursor down 


le 


Move cursor left 


nd 


Non-destructi>« q>ace (cursor right) 


cm 


Cursor movement 


im 


Insert mode 


el 


End insert mode 


ic 


Insert characto' 


al 


Add line 


dl 


Delete line 


dc 


Delete Character 


ho 


Move cursor to home position 


ce 


Clear to end of line 


cd 


Clear to end of display 


cl 


Clear screen 


vh 


Visible bell 


so 


Begin standout mode* 


se 


End ^dout mode* 


kh 


Sequence transmitted by Home key** 


kr 


Sequence transmitted by cursor-right key** 


kl 


Sequence transmitted \^ Cutsor-left k^** 
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ku Sequence transmitted by cursor-up key** 

Sequence transmitted by cursor-down key** 

AT Attribute type (STSC enhancement)* 

AP Attribute prefix (STSC tttfijtticwttent)* 

AO - A8 AtUibute codes (STSC enhancement)* 

SC Spaces clear flag (STSC enhancement) 

SO. Spaces overstrifce (STSC aihancon^t) 

SR Spaces iqdace (STSC enhancement) 

* Standout mode is used ifthe STSC odiancedtennciq) notation fiv 

attributes is not present in the file. See "Termcap Notation for 
Display Attributes," following, for a discussion of the STSC 
enhvKsements. 

. J,. ** APL will extract the logical keystrokes for cursor movement from 
^ r^.J^ die fSincapffle if these entries are present, in which case it is not 
necessary to caqdicitly define them in the configuration file. 

Regular UNIX termcap files only contain the information necessary to 
support one logical attribute, known as "standout mode". When APL 
is used with a regular termcap file, standout mode is used tp produce 
display attribute 1, tel alti^aK 2, 4, and 8 m (dEEesL 
Depending upm the teiminal, attribute 1 m^ be revose v^eo (V 
something differait 



To provide a more complete set of attributes, the APL* PLUS System 
supports extensions to termcap that describe how attributes are 
piodaeed cm a wmkai, AFL handles two i^sam. nvays in wMdi 
terminals control comMoations display attributes called Type 0" 
and "Type 1": 

• On "Type 0" terminals, attributes are set individually, with a 
separate escape sequence used to set each attribute. APL sets the 
attributes on Itiese terminals by first transmitting fte "el^ all 
attributes" sequence and then transmitting a separate escape sequence 
to turn on each desired attribute. Terminals that follow the ANSI 
standard, such as the DEC VTIOO and VT200, are common 
examples of Type 0 terminals. 
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• On "Type 1" terminals, the display attributes are set by m esc^ 
sequence followed by an "attribute byte" that expresses ^ desired 
combination of attributes to be turned on. The APL *PLUS PC 
System in terminal mode is an example of a Type 1 terminal. 

The following tables descibe how termcap entries are constructed for 
both types of terminals. The STSC termcap file atermcap contains 
examples of eadi type of attribute encoding. 



Attribute Notation for Type 0 Terminals 
Name Use 

AT attrSNitB type: at=0 means that this is a Type 0 
terminal, «dth each attribute turned on individually 

AO default attribute (0): tiaiffiRMigtiiis seqiiBnce to die 
terminal will reset tfie tenninal to its default display 
attribute 

Ai stiing tomMftm^jm 1 (jtevm& \iam) 

A2 String to emble attribute 2 (alternate intensity) 

A3 string to enable attribute 4 (blinking) 

A4 String to enable attribute 8 (undoUne) 

A5 String to enable attribute 16 

A6 string to enable attribute 32 

A7 string to enable attribute 64 

A8 String to enable attribute 128 



Attribute Notation for Type 1 Terminals 
Name Use 

AT attribute type: AT«1 means that this is a Type 1 terminal 
with all attributes set by one attribute byte 

AP attribute prefix: the invariant part of the escape sequence 
that sets the attribute byte; AFi, transmits this sequence 
to the terminal followed by a single byte computed to 
doiote all of the attributes 
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AO default attribute (0): a single character that represents the 
default attribute; the attribute characters for the other 
attributes are added to the decimal value of this character to 
compute the attribute byte; typically, AO is ddier SPACE 
or "@" (decimal 32 or 64) 

Al character added to AO for attribute 1 (reverse video) 

A2 characto- for aoriboie 2 (aKemaie iitteifflty) 

A3 character for attribute 4 (blinking) 

A4 character fw attribute 8 (underline) 

A5 character for attribute 16 

A 6 character for attribute 32 

A7 character for attribute 64 

A8 charactor for attribute 128 



For example, on a Type 1 terminal where 

A0="@ " (decimal value 64) 
Al=Ctrl D (decimal value 4) 
A2=CirlH (decimal valw 8) 



Afl. would set attribute 3 by transmittmg die AP i^ri^i foUDwed by 
the ASCn character 1." (whose decimal wiim 76 is 64+4+8). 

O^STSC Termnqf Enhammvents 



In addition to the enhanced notation for display attributes, STSC has 
also i^fined three new tefflK^q) eontfol sftdnfs. tbesb stfteigs control 
the means by which UVPUT writes data to the terminal screen when 
(Hdy a portion of the screen is being updated. On many APL 
ieimiials, is necessary to first blaidc out the characters aheady 
presefSon the screen before the new data is written, since the tmninals 
will ovecstrike the existing data instead of replacing it. 



The new strings are 



sc FI^ to indicate that the terminal always ovmvites data 

already present on the screen, even in APL mode. This is 
true of non-overstriking terminals such as the VT2(X). If the 
Vimsap entry contains : SC : , □ VP(/r will not blank out 
an area before ovowiiting it 
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io=... SC is abs^t, Ms is the string used to put ttie t^miml 
into a state wtoSi^ces overstrike rather thim leplaoe 
iKiisting chaiact@rs. Default is so='^n. 

SR=... If SC is absent, this is the string used to put the teitninal 

into a state wbere spaces replace existing chatact^, enabling 
□VPyf to teliabiy blank out an area (OT Defatilt 
is SR"*©. 
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Appendix E 

Policy On Commercial Use 

And Distribution ofKermit 



STSC provides Kermit with this APL *PUJS System in accordance 
■with the following policy statement written by Frank da Crux, 
Cphml^ Umeraty Center far Computing Activities, June 1984: 

The KERMIT file transfer piotoccd has alvrays been open, avaiUble, 

and free to all. The protocol was develq)ed at the Columbia 
University Center for Computing Activities, as were the first several 
KERMIT programs. Columtyia has shared diese piOgranis fieely with 
the worldwide computing community since 1981 , and as a result many 
individuals and instituti(»s have contributed their own improvements 
or new implementatiois in the same spirit tn Ms mumer, the 
number of different systems supporting KERMIT implementations has 
grown from three to about sixty in less than three years. If Columbia 
had elected to keep the proitjecd se^et, to eestntt access 10 scHKe code, 
or to license the software, the protocol would never have spread to 
cover so many systems, nor would the programs be in use at so many 
sites, m^^^^old the ^lality of mai^ ot ibe implementatimis be so 
high.^ 

Although KERMIT is free and available to anyone who requests it, it 
is not in the "public domam". The protocol, the manuals, the 
Columbia implemoitations, and many of the ccsitributed 
implementations bear copyii^t notices dated 1981 or lata, and include 
aleg^like 

Permission is granted to any individual or institution to copy 
or use this document and the programs described in it, excq>t 
for explicitly commercial pnif)oses. 

This copyright notice is to protect KERMIT, Columbia University, 
ahif iie^i^OQS contr9nitors tarn havnng ifaejr woilc osorped byodieis 
and sold as a product. In addition, the covering letter which we include 
with a KERMIT tape states that KERMIT can be passed along to 
others: "we ask only that profit not be your fsal^ &eM be ^ven whoe 
. U i^ ,dij^.^d that new matraial be sent back to us so that we can 



maintain a definitive and comprehensive set of KERMTT 
imideinentations." 

Within this framework, it is acceptable to charge a reproduction fee 
wbrasiqiplying KERMTT to othm. lite it^MO^iedOii fee inay he 

designed to recover costs of media, packaging, printing, shipping, 
order processing, or any computer use required for reproduction. The 
fee should not reflect any ptx)gram or documentation development 
effort, and it should be independent of how many implementations of 
KERMIT appear on the medium or where ihey came from. It should 
not be viewed as a license fee. For instance, when Columbia ships a 
KERMTT tape, there is a S 100.00 reproduction fee which includes a 
2400' reel of magnetic tape, two printed manuals, various flyers, a 
box, and postage; there is an additional $100.00 order processing 
change if an invoice must be sent The tape includes all known 
versions of KERMTT, including sources and documentation. 

Comm^cial institutions may make unlimited internal use of 
KERMFT. However, a quesiton raised with increasing frequency is 
whether a company may incorporate KERMIT into its products. A 
hardware vendor may wish to include KERMTT protocol into its 
comunications package, or to disoihate it along with some other 
product. A timesharing vendor or dialup database may wish to provide 
KERMIT for downloading. AU these uses of KERMIT are 
permissible, with ilie folk^ng firovssos; 

• A KERMIT program may not be sold as a product in and of itself. 
In aMtkm to violating die pre^btg sfMt of sharing m& 
cooperation, commercial sale of a product called "KERMIT" would 
violate the trademark which is held on that name by Henson 
Assodates, Inc., oeators The Muppet Show. 

• Existing KERMIT programs and docimientation may be included 
with hardware or other software as part of a standard package, 
provided the price of the hardware or software product is not raised 
significantly beyond costs of reproduction of the KERMIT 
component 

• KERMTT protocol may be included in a multi-protocol 
communication package as one of the communication options, or as 
a communication feature of some other kind of software package, in 
order to enhance the attractiveness of the package. KERMTT 
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prdtdcol file transfer and management should not be the primary 
purpose of the package. The price of the package should not be 
raised significantly because KERMIT was included, and the vendor's 
litoature should make a statement to this effect. 

• Credit for development of the KERMIT protocol should be given to 
the Columbia University Cum for Computing Actividra, and 
customers should be advised that KERMIT is available for many 
systems for only a nominal fee from Columbia and from various 
usor groop orgifflizaittms, such as DBCUS and SHARE. 

Columbia University holds the copyright on the KERMIT protocol, 
and may grant permission to sny p&sm Hf ii^tiition develq> a 
KERMIT program for any particular system. A commercial 
institution that intends to disuibute KERMIT under the conditions 
listed above should be aware that other implementations of KERMIT 
for the same system may appear in the standard KERMIT distribution 
at any time. Columbia University encourages all developers of 
KERMIT software and documentation to contribute thdr wmk back to 
Columbia for further distribution. 

Finally, Columbia University does not warrant in any way the 
KERMIT software nor the accuracy of any related documentation, and 
neitho- die autfiors of any KERMITpropans or docnnieaiKiion nor 
Columbia University acknowledge any fiability resulting from 
program or documentation enors. 

These are general guidelines, not a legal document to be searched for 
loopholes. To date, KERMIT has been freely shared by all who have 
taken die timi to do work on it, mA m MmA IsgalMBS have proven 
necessary. The guidelines are designed to allow commercial enterprises 
to participate in the promulgation of KERMIT without seriously 
violating the KERMIT user conunmiity's trust that KERMIT will 
continue to spread and improve at no significant cost to themselves. 
The guidelines are subject to change at any time, should more formal 
detail prove necessary . 

Commercial organizations wishing to provide by KERMIT to their 
customers should write a letter stating their plans and their agreement 
to comply with the guidelines lis^ above. The letter should be 
addressed to: 



KERMTT Diistributiai 

Colombia University Center for Compating Activities 

612 West 115th Street 

NewYofk,NY1002S 
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Index 



U = APL *PLUS System User's Manual 
R = APL *PLUS System Reference Manual 

) 2-5 R 
Access (s^ 

Access matrix (see Files) . r - 1' 
Accounting infoimation 

OAt 3-9 R 

Alphabets 1-15 U 
DALX 3-10 R 

APL convmand procedure 1 -4 U 

APL component files (see Files) 

APL session 1-2 U 

i4 PL CO(/*S£ workspace 9-2 U 

Aplotab file 1-22 U , . 

DARBIN 6-\V..l-U,&. 

Arbitrary a^^gm^jt^ta^Bak-^^^ 

Arbitrary ouput to terminal (sm'WI^OUT) 

DilfiJOUr 5-2 U, 3-17 R 

ASCn terminal 1-12 U 

Atermcap file D-1 U 

Atomic vector (sec DAV) 

Attention latent expression (see QALX) 

DAV B-1 U, 3-18 R 

AXIS ERROR C-1 U .. 

Bitotab file 122 U 

Capqid^^e^^entation of a flection, 

(seedCSwd QCBL) 
Character set (see QAY) 
DCHDIR 3-20 R 

) CLEAR 2-6 R 
)CMD 7-2 U, 2-8 R 
nCMD 3-21 R 

Communications overview 6-1 U 
Comparison tolerance (see OCT) 
COMPLEX workspace 9-3 U 
Configuration files 1-28—1-29 U 
Convasion of data (see OF J) 

) copy 2-9 R 



DCOPY 3-23 R 
nCR 3-25 R 
QCRL 3-26 R 
QC&LPC 3-28 R 
QCT 3-29 R 

nCURSOR 5-3 U, 3-31 R 
Cursor movement 1-16 U 
Cursor position (see QCURSQR) 

Data conversion (see Of J) 

Data representation (see 

DATES workspace 9-5 U 

UDEF 3-32 R 

QDEFL 3-35 R 

Del editar ^-M-^Z-M U 

eaots 2-2617 
Delay execution (see DDL) 
DEMOAPL workspace 9-6 U 
Diagnotsic message (see 0 DM) 
DISK ERROR C-1 U 
Display attributes 5-4 U 
DDL 3-38 R 
DDM 3-39 R 

DOMAIN ERROR C-1 U 
UDR 3-42 R 
)DROP 2-11 R 
DTFNtm^m 6-711 
dtfhJUUl imm&m ^7 U 

DEDIT 2-14 U. 3-^ R . 

)EDIT 2-14W.,2-mR 
Editmem= 1-20 U 
EIGENVAL workspace 9-7 U 
UELX 3^R 

Erase objects (see QERASE and Qflf) 
)ERASE 2-13 R 
nSRASE 3-41 R 

Error excqjtion signal (see UERROR) 
Error latent expression (see UELX) 
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DERROR 3-48 R 
Errors, listed C-1 U 
DEX 3-51 R 

External processes 7-4 — 7-10 U 

defined 7-3 U 

structure 7-8 — 7-10 U . 

writing 7-8 U 
External routines 7-10—7-21 U 

defined 7-3 U 

nFAPPEND 3-52 R 
OFAVAIL 3-54 R 
UFCREATE 3-7—3-9 U, 3-55 R 
DFDROP 3-17 U, 3-57 R 
QFDUP 3-23 U, 3-58 R 
QFERASE 3-12U.3-60R 
OFHIST 3-61 R 
OFHOLD 3-27— 3-31 U, 3-62 R 
QFI 5-7 U, 3-64 R 

Hie system availal^i^ (see OFAVAIL) 
FILE ACCESS ERROR C-1 U 
FILE ARGUMENT ERROR C-1 U 

FILE DAMAGED C-1 U 
FILE DATA ERROR C-2U 
FILE FULL C-2U 
FILE INDEX ERROR C-2U 
FILE NAME ERROR C-1 U 
FILE NAME TABLE FULL C-2U 
FILE NOT FOUND C-2U 
FILE TIE ERROR C-2U 
FILE TIE QUOTA ETCEBBED C4U 
FILE TIED C-2U 
) FILE HELPER 2-14 R 
Files 3-1—3-43 U 
access 3-3 U 

access matrix 3-24 — ^3-26, 3-32—3-38 U 

defined 3-35 U 

example 3-37 U 

override (see )FILEHELPER) 
contacting 3-23 U 
conq>adson vddl wodcqiaiees 3-4 U 
component infonnatkia (see UFSDCI) 
components 3-2 U 
copying (see UFDUP) 
creating (see OFCREATE) 
dropping components (see QFDROP) 
erasing (see QFERASE) 



examples 3-19 U 
libraries 3-3 U 

default 3-39 U 

defined 3-38 U 

listing (see DFLIE) 
native files 3-3, 3-43, 7-1 U 

comparison with APL files 3-14 
3-40 U 

sample handling 3-13 U 
passnumbers 3-35 U 
reading (see UFREAD) 
renaming (see DFRENAME) 
replacing components 

(see OFREPLACE) 
sharing ties 

(see UFSTIE and QFHOLD) 
size (see QFSIZE) 
Siase&yt (ftienFRESIZE) 
tie ioiteMies (see OFHAMES and 

QFNmS) 
tying (see DFTIE) 
untying (see UFUNTIE) 
)FLIB 2-15 R 
UFLIB 3-11 U, 3-65 R 
DFMT 3-67 R, 4-1^-39 U 
arguments 4-4 — 4-7 U 
data list 4-4 U 
decorators (see modifiers) 
defined 4-3 V 
^me^ 4^% 4-34 U 
format phrases 4-9 — 4-17 U 

character editing 4-9 U 

exponential editing 4-11 U 

integer editing 4-10 U 

pattern editing 4-12 U 

positioning 4-14 — 4-17 U 

text 4-14^-17 U 
format string 4-6 — 4-8 U 
grouping symbols 4-21 U 
modifier 4-^-4-34 U 
panEmenss 4-18 — 4-21 U 
mts m restdt 4-34 U 
tutorial 4-1—4-39 U 
OFNAMES 3-15 U. 3-70 R 
OFNUMS 3-15 U, 3-71 R 
)FNS 2-16 R 
Fonnat ouput (see UFMT) 
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F9MMAT ERROR C-3U . 
J'PlKMr; workspace 436— 4^9 U 
Fbnnatting (see QFMT) 
UFRDAC 3-32 U, 3-72 R 

UFRDCI 3-26 U, 3-73 R 
OFREAD 3-11 U, 3-75 R 
DFRENAME 3-21 U, 3-77 R 
OFREPLACE 3-16 U, 3-79 R 
OFRESIZE 3-21 U, 3-81 R 
UFSIZE 3-18 U, 3-82 R :. 
UFSTAC 3-32 U, 3-83 R ..t.^c'^ "^-s 
QFSTJE 3-27 U. 3^=85 U a :, : 
QFTIE S.10O*3-8m - V 

oommancl mode 2-13 U 

commands 2-4 — 2-14 U .. /. 

errors 2-16—2-19 U 

status line 2-4 U 
Function definition (see □ DEF) 
Function definition mode 2-21 U 
Function fix (see DFX) 
DF UNTIE 3-9 U, 3-89 R- 
OFX 3-90 R 

? I ■ 

in>Stennmi(t M2U 
)HELP 2-17 R 
Help= 1-20 U 

HOST ACCESS ERROR CSV 

Identifier list 

(see niDLIST and niDLOC) 
niDLIST 3-92 R < • '•• - 

DIDLOC 3-94R 
INCOMPATIBLE WS C-3 U 
INCORRECT COMMAND C-3V. 
Index origin (see □JO) ' " ' '.^ --i 
INDEX ERROR C-3 U ' ' 

Mtmes 141 U 
Mdalwss 1-21 U 
niNKEY 5-5 U, 3-96 R 
Input format conversion (see Df I) ; 
Input format verification (see QVI) 
Input management 5-1 — 5-7 U 
INPUT workspace 5-8—5-13 U 
Insert mode 1-14 U 'T.^^•^ 
INSUFFICIENT MEMORY C-?>\J - 



INSUFFICIENT PROCESS SPACE 
G-3U 

Internal data rei^esentatipns A-1 y 
Internal structures 10-6 U 
Interrupting APL 1-13 U 
010 3-97 R 
IPCHR function 5-11 U 
IPMATCH function 5-12 U 
IPMIX function 5-12 U 
IPNUM function 5-11 U 

Kerroit 611 U 

^Miriita^B |[#^ S^l U 
Keyboani 1-9—1-15 U 

Latent expression (see DL jf ) 
□ LC 3-99 R 

LENGTH ERROR C-4U 
LfSSOWS workspace 9-7 U 
LFFN function 6-7 U 
)LIB 2-18 R 
DLIB 3-100 R 
QLIBD 3-101 R 
)LIBS 2-19 R 
PLUS 34iaR 
Librtaies (isee Filra) 
library define (see ULIBD) 
Library list (see OLIB and ULIBS) 
LIBRARY NOT FOUND C4U 
library^ 1-22 U 
LIMIT ERROR CAU 
Line counter (see OLC) 
)LOAD 2-20 R 
ULOAD 3-103 R 
QLOCK 3-104 R 
Logical keystrokes 1-9 U 
customizing 1-26 U 
ULX 3405 R 

Memory considerations 10-1 U 
UMF 10-4 U, 3-106 R 
Monitor function (see UMF) 

UNA 7-1, 7-10—7-21 U, 3-108 R 
case study 7-19 U 
errors 7-16 U 

writing your own routines 7-17 U 
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Name classification (see UNC) 

Name list of identifiers (see DNL) 

UNAPPEND 3-111 R 

QNC 3-113 R 

QNCREATE 3-114 R 

UNERASE 3-116 R 

DNL 3-117 R 

QNNAMES 3-U9R 

ONNUHS 3420 R 

NO SPACE FOR QDM CAV 

Non-APL Routine (see UNA) 

NONCE ERROR C4U 

NOT COPIED CAV 

NOT COPIED, WS DAMAGED C-4U 

NOT ERASED C4 U 

NOT FOUND C-4U 

NOT IN DEFN OR QUAD C-5 U 

QNRDAC 3-121 R 

UNREAD 3-123 R 

UNRENAME 3-12SR 

UNREPLACE 3426 R 

□J/SIZf 3-128 R 

□ ^/ST^C 3-129 R 

UNTIE 3-131 R 

QNUNTIE 3432 R 

)OFF 2-22 R 

Output management 5-1 — ^5-7 U 
Oiiipattrt= 1-22 U 
Ovnstrike mode 1-14 U 
Oventrikes 1-14 U 

Paging 10-2 U 

PC as a terminal 1-6 — 1-9 
)PCOPY 2-23 R 
OPCOPY 3-133 R 
PF keys 5-5, 5-6 U 
UPFKEY 3-135 R 
) PORTS 2-24 R 
UPP 3-137 R 
PiWtiQg 8-1 U 
Plbi^ jspt^am Owe QPP) 
Rcintb^ widat (see OPV) 
UFR 3-138 R 

Pronq)t replacement (see UPR) 

Ptompt= 1-23 U 

Protected copy (mcUPCOPY) 



)PSAVE 2-25 R 
aPSAYE 3-140 R 
□ PW 3-142 R 

UQLOAD 3-143 R 
Quad (D) input 5-1 U 
(Juietload (seeUQLOAD) 
Quote-quad (□) input 3-1 U 

RmdonUnk (see USL) 
RANK ERROR C-5 U 

Rawotab file 1-22 U 
References, multiple 10-5 U 
Replace mode 1-14 U 
) RE SET 2-26 R 
Ring, editing 2-2 U 
QRL 3-144 R 

USA 3-145 R 
)SAVE 2-17 R 
nSAVE %-mK 
Screens= 1-24 U 

Scrolling 1-17 U 
SERHOST workspace 6-4—6-6 U 
SERXFER workspace 6-4—6-6 U 
Session Manager 1-16 — 1-18 U 
Session parameters 1-18-— 1-28 

list 1-19 U 
Set Host command 6-1 1 U 
Shared code s^ment 10-3 U 
)SI 2-29 R 
aSI 3450 R 
)SIC 2-30 R 
)SINL 2-31 R 
OSIZE 3-151 R 
SLT workspace 6-9 U 
Software requirements 1-1 U 
Source level transfer 

(see SLT workspace) 
USS 3-153 R 
State indicator (see US I) 
Status^ 144 U 
Stop acdea (cee USA) 
Stop funeticm execution (^ee USTOP) 
USTOP 3-154 R 
String search (see □ 55) 
) SYMBOLS 2-32 R 
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nSYMB 3-157 R 

SYNTAX ERROR C-5 U 

QSYSID 3-158 R 

System identifier (see OS 7 SID) 

System limits A-1 U 

System version (see OSYSVER) 

SYSTEM ERROR C-5U 

aSYSVER 3-159 R 

QTCBEL 5-2 U. 3-160 R 

UTCBS 5-2 U, 3-160 R 

UTCDEL 5-2 U, 3-160 R 

DTCESC 5-2 U, 3-160 R 

OTCFF 5-2 U, 3-160 R 

QTCLF 5-2 U, 3-160 R 

QTCNL 5-2 U, 3-160 R 

QTCNUL 5-2 U, 3-160 R 

Tomcap database 1-25 U, D-1 U 

Termcap entries D-2 U 

Termcap= 1-25 U 

T^dintts 1-24 U 

t«mulml randiQl codes (see OTCXX) 

Tomina^ 1-25 U 

Terminals supported 1-2, 1-4 U 

Terminit= 1-24 U 

Timestamp (see QTS) 

Trace function execution (see tlTRACE) 

nTRACE 3-163 R 

TRANSFER workspace 6-6—6-8 U 

Transferring data 6-2 U 

Translate table 1-22 U 

UTS 3-165 R 



VT220tabfile 1-22 U 

DVA 3-170 R 
DWGET 5-4 U 
DVGET 3-171 R 

Window data (see QWPUT and QVGET) 

Window specification (see OVINDOV) 

QWINDOU 3-173 R 

Wo& area svailaMe (si« Dl/A) 

Workspaces 

comparison with files 3-4 R 
supplied with system 9-1 — ^9-8 U, 
4-1—4-25 R 

nWPUT 5-3 U, 3-174 R 

VS ARGUMENT ERROR C-5 U 

WS DAMAGED C-5 U 

US FULL 10-3 U, C-5 U 

WS NAME ERROR C-5 U 

VS NOT FOUND C-5 U 

VS TOO LARGE CSV 

)WSID 2-34 R 

nVSID I.176R 

)VSLIB 2^SR 

nVSLTS 3-177 R 

OWSOVNER 3-179 R 

aWSSIZE 3-180 R 

aVSTS 3-181 R 

OXLOAD 3-182 R 

nXP 7-1, lA U, 3-183 R 



aUL 3466 R 
UNBLOCKS foBB&m 6-7 U 
User identificaHm ^ UUSESID) 
User load (see UUL) 
OUSERID 3-167 R 
UTILITY workspace 9-8 U 

VALUE ERROR C-5 U 

)VARS 2-33 R 

DVI 5-7 U, 3-168 R 

Visual representation of a function 

(see QVR) 
nVR 3-169 R 
VT220 trammal 1-6 U 
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